docs/openapi.yaml · aaronrene/knowtation

summary: Import from uploaded file or ZIP (multipart: source_type; file except for google-sheets; optional project, tags, spreadsheet_id for google-sheets)

2126

requestBody:

2127

required: true

content:

multipart/form-data:

schema:

type: object

required: [source_type]

properties:

source_type:

type: string

description: Importer id. For google-sheets, omit file and set spreadsheet_id; optional sheets_range (A1 notation). See lib/import-source-types.mjs.

2137

file: { type: string, format: binary, description: Required for all importers except google-sheets. }

2138

spreadsheet_id:

2139

type: string

2140

description: Required when source_type is google-sheets (id from the Google Sheets URL).

2141

sheets_range:

2142

type: string

2143

description: Optional for google-sheets; A1 range. Omit to read the first sheet from A1.

2144

project: { type: string }

2145

output_dir: { type: string }

2146

tags: { type: string }

responses:

'200':

content:

application/json:

schema:

type: object

properties:

imported: { type: array, items: { type: object } }

'400':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

'500':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

/import-url:

post:

tags: [Notes]

summary: Import from a public https URL (JSON body; editor/admin)

requestBody:

required: true

content:

application/json:

schema:

type: object

required: [url]

properties:

url: { type: string, description: 'Full https URL' }

2178

mode: { type: string, enum: [auto, bookmark, extract], description: 'Capture mode (default auto)' }

2179

project: { type: string }

2180

output_dir: { type: string }

2181

tags: { oneOf: [{ type: string }, { type: array, items: { type: string } }] }

responses:

'200':

content:

application/json:

schema:

type: object

properties:

imported: { type: array, items: { type: object } }

'400':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

'500':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

/docs/connectors:

get:

tags: [DocsConnectors]

2203

summary: List docs connectors (Drive + Notion). Gate off → 501 NOT_AUTHORIZED. No secrets.

responses:

'200':

content:

application/json:

schema:

type: object

required: [schema, connectors]

2211

properties:

2212

schema: { type: string, enum: [knowtation.docs_connectors/v0] }

connectors:

type: array

items:

type: object

properties:

connector_id: { type: string }

2219

provider: { type: string, enum: [google-drive, notion] }

2220

display_name: { type: string }

2221

status: { type: string, enum: [pending, connected, needs_reauth, revoked] }

2222

last_sync_at: { type: string, nullable: true }

2223

last_sync_error: { type: string }

2224

file_count: { type: integer }

2225

revoked_at: { type: string, nullable: true }

2226

'501':

2227

description: Gate not authorized

2228

post:

2229

tags: [DocsConnectors]

2230

summary: Begin Drive OAuth or Notion Hub-key connector (editor/admin). Gates hard-coded false.

requestBody:

required: true

content:

application/json:

schema:

type: object

required: [provider]

properties:

provider: { type: string, enum: [google-drive, notion] }

2240

display_name: { type: string, maxLength: 128 }

2241

return_url: { type: string, description: Required for google-drive; exact-allowlisted }

2242

responses:

2243

'200':

2244

description: Drive returns authorization_url; Notion returns status

2245

'400':

2246

description: BAD_REQUEST / PROVIDER_DENIED / RETURN_URL_DENIED

2247

'501':

2248

description: NOT_AUTHORIZED

2249

2250

/docs/connectors/callback:

2251

get:

2252

tags: [DocsConnectors]

2253

summary: Google Drive OAuth callback (state-authenticated; no JWT)

security: []

parameters:

- name: code

in: query

schema: { type: string }

2259

- name: state

2260

in: query

2261

schema: { type: string }

2262

responses:

2263

'302':

2264

description: Redirect to allowlisted return_url

2265

2266

/docs/connectors/{id}/files:

2267

get:

2268

tags: [DocsConnectors]

2269

summary: List importable file metadata (no bodies)

parameters:

- name: id

in: path

required: true

schema: { type: string }

2275

- name: page_token

2276

in: query

2277

schema: { type: string }

2278

- name: q

2279

in: query

2280

schema: { type: string, pattern: '^[A-Za-z0-9 ._-]{1,128}$' }

2281

responses:

2282

'200':

2283

description: files + optional next_page_token

2284

'400':

2285

description: BAD_REQUEST (invalid q or ids)

2286

'501':

2287

description: NOT_AUTHORIZED

2288

2289

/docs/connectors/{id}/import:

2290

post:

2291

tags: [DocsConnectors]

2292

summary: Create docs-sync Review proposals for 1–20 file ids (never writeNote)

parameters:

- name: id

in: path

required: true

schema: { type: string }

requestBody:

required: true

content:

application/json:

schema:

type: object

required: [file_ids]

properties:

file_ids:

type: array

minItems: 1

maxItems: 20

items: { type: string }

2311

responses:

2312

'200':

2313

description: '{ proposed, skipped, proposal_ids }'

2314

'501':

2315

description: NOT_AUTHORIZED

2316

2317

/docs/connectors/{id}/sync:

2318

post:

2319

tags: [DocsConnectors]

2320

summary: Optional cursor sync; rate-limited ≥60s; creates proposals only

parameters:

- name: id

in: path

required: true

schema: { type: string }

2326

responses:

2327

'200':

2328

description: '{ proposed, skipped, last_sync_at }'

2329

'429':

2330

description: RATE_LIMITED

2331

'501':

2332

description: NOT_AUTHORIZED

2333

2334

/docs/connectors/{id}:

2335

delete:

2336

tags: [DocsConnectors]

2337

summary: Revoke connector; imported vault notes stay

parameters:

- name: id

in: path

required: true

schema: { type: string }

2343

responses:

2344

'200':

2345

description: '{ revoked: true }'

2346

'501':

2347

description: NOT_AUTHORIZED

/settings:

get:

tags: [Notes]

summary: Config status for Settings UI (no secrets)

responses:

'200':

content:

application/json:

schema:

type: object

properties:

vault_path_display: { type: string }

vault_git:

type: object

properties:

enabled: { type: boolean }

2365

has_remote: { type: boolean }

2366

auto_commit: { type: boolean }

2367

auto_push: { type: boolean }

/vault/sync:

post:

tags: [Notes]

summary: Manual vault backup (git add, commit, push)

2373

description: Self-hosted runs local git. Hosted (bridge) pushes notes as Markdown plus `.knowtation/backup/v1/snapshot.json` with full proposals.

responses:

'200':

content:

application/json:

schema:

type: object

properties:

ok: { type: boolean }

2382

message: { type: string }

2383

notesCount: { type: integer, description: Hosted bridge only }

2384

proposalsCount: { type: integer, description: Hosted bridge only }

'400':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

'500':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

/search:

post:

tags: [Search]

summary: Vault search (semantic or keyword)

requestBody:

required: true

content:

application/json:

schema:

type: object

required: [query]

properties:

query: { type: string }

2407

mode: { type: string, enum: [semantic, keyword], description: Omitted or semantic = vector search; keyword = substring/token match on note text }

2408

match: { type: string, enum: [phrase, all_terms], description: Keyword only; phrase = full query substring; all_terms = every token must appear }

2409

folder: { type: string }

2410

project: { type: string }

2411

tag: { type: string }

2412

since: { type: string }

2413

until: { type: string }

2414

chain: { type: string }

2415

entity: { type: string }

2416

episode: { type: string }

2417

limit: { type: integer }

2418

order: { type: string }

2419

fields: { type: string }

2420

content_scope: { type: string, enum: [notes, approval_logs], description: Narrow to normal notes vs approvals/ logs }

2421

snippetChars: { type: integer }

2422

count_only: { type: boolean }

2423

countOnly: { type: boolean }

responses:

'200':

content:

application/json:

schema:

type: object

properties:

results: { type: array, items: { $ref: '#/components/schemas/SearchResult' } }

2432

query: { type: string }

2433

mode: { type: string, enum: [semantic, keyword] }

'400':

content:

application/json:

schema: { $ref: '#/components/schemas/Error' }

/proposals:

get:

tags: [Proposals]

summary: List proposals

parameters:

- name: status

in: query

schema: { type: string }

2448

- name: limit

2449

in: query

2450

schema: { type: integer }

2451

- name: offset

2452

in: query

2453

schema: { type: integer }

2454

- name: label

2455

in: query

2456

description: Match if proposal labels include this string (case-insensitive)

2457

schema: { type: string }

2458

- name: source

2459

in: query

2460

schema: { type: string }

2461

- name: path_prefix

2462

in: query

2463

schema: { type: string }

2464

- name: evaluation_status

2465

in: query

2466

description: Filter by evaluation_status (none, pending, passed, failed, needs_changes)

2467

schema: { type: string }

2468

- name: review_queue

2469

in: query

2470

description: Exact match on proposal review_queue

2471

schema: { type: string }

2472

- name: review_severity

2473

in: query

2474

description: standard or elevated

2475

schema: { type: string }

responses:

'200':

content:

application/json:

schema:

type: object

properties:

proposals: { type: array, items: { $ref: '#/components/schemas/Proposal' } }

2484

total: { type: integer }

2485

post:

2486

tags: [Proposals]

2487

summary: Create proposal

requestBody:

content:

application/json:

schema:

type: object

properties:

path: { type: string }

2495

body: { type: string }

2496

frontmatter: { type: object }

2497

intent: { type: string }

2498

base_state_id: { type: string }

2499

external_ref: { type: string }

2500

labels: { type: array, items: { type: string } }

2501

source: { type: string }

responses:

'201':

content:

application/json:

schema:

type: object

properties:

proposal_id: { type: string }

2510

path: { type: string }

2511

status: { type: string, enum: [proposed] }

'400':

/proposals/{id}:

get:

tags: [Proposals]

summary: Get one proposal

parameters:

- name: id

in: path

required: true

schema: { type: string }

responses:

'200':

content:

application/json:

schema: { $ref: '#/components/schemas/ProposalDetail' }

2528

'404':

2529

2530

/proposals/{id}/review-hints:

2531

post:

2532

tags: [Proposals]

2533

summary: Store async LLM review hints (canister; not a merge gate)

parameters:

- name: id

in: path

required: true

schema: { type: string }

requestBody:

content:

application/json:

schema:

type: object

properties:

review_hints: { type: string }

2546

review_hints_model: { type: string }

responses:

'200':

content:

application/json:

schema:

type: object

properties:

proposal_id: { type: string }

2555

ok: { type: boolean }

2556

2557

/proposals/{id}/evaluation:

2558

post:

2559

tags: [Proposals]

2560

summary: Submit human evaluation (admin or evaluator)

parameters:

- name: id

in: path

required: true

schema: { type: string }

requestBody:

content:

application/json:

schema:

type: object

required: [outcome]

properties:

outcome:

type: string

enum: [pass, fail, needs_changes]

checklist:

type: array

items:

type: object

properties:

id: { type: string }

passed: { type: boolean }

2583

grade: { type: string }

2584

comment: { type: string }

responses:

'200':

content:

application/json:

schema: { $ref: '#/components/schemas/ProposalDetail' }

'400':

'404':

/proposals/{id}/approve:

2594

post:

2595

tags: [Proposals]

2596

summary: Apply proposal to vault

parameters:

- name: id

in: path

required: true

schema: { type: string }

requestBody:

content:

application/json:

schema:

type: object

properties:

base_state_id: { type: string }

2609

waiver_reason:

2610

type: string

2611

description: Admin override when evaluation is not passed (min length 3 after trim)

2612

external_ref:

2613

type: string

2614

description: Optional cross-system lineage id (e.g. Muse); server may resolve via MUSE_URL when omitted

responses:

'200':

content:

application/json:

schema:

type: object

properties:

proposal_id: { type: string }

2623

status: { type: string, enum: [approved] }

2624

external_ref: { type: string }

2625

'403':

2626

description: EVALUATION_REQUIRED — pass evaluation or provide waiver_reason

2627

'409':

2628

description: base_state_id mismatch (CONFLICT)

2629

2630

/proposals/{id}/enrich:

2631

post:

2632

tags: [Proposals]

2633

summary: Optional LLM summary and suggested labels (KNOWTATION_HUB_PROPOSAL_ENRICH=1)

parameters:

- name: id

in: path

required: true

schema: { type: string }

responses:

'200':

content:

application/json:

schema: { $ref: '#/components/schemas/ProposalDetail' }

2644

'400':

2645

description: >-

2646

ICP canister — suggested_labels_json or assistant_suggested_frontmatter_json is valid JSON

2647

but exceeds max length (4000 / 14000 characters) after validation.

2648

'404':

2649

2650

/proposals/{id}/discard:

2651

post:

2652

tags: [Proposals]

2653

summary: Discard proposal

parameters:

- name: id

in: path

required: true

schema: { type: string }

responses:

'200':

content:

application/json:

schema:

type: object

properties:

proposal_id: { type: string }

2667

status: { type: string, enum: [discarded] }

/capture:

post:

tags: [Capture]

summary: Ingest message into vault inbox (webhook-style)

2673

description: Same contract as capture-webhook. If CAPTURE_WEBHOOK_SECRET is set, require X-Webhook-Secret header.

security: []

requestBody:

content:

application/json:

schema:

type: object

required: [body]

properties:

body: { type: string }

2683

source_id: { type: string }

2684

source: { type: string }

2685

project: { type: string }

2686

tags: { type: array, items: { type: string } }

responses:

'200':

content:

application/json:

schema: { type: object, properties: { ok: { type: boolean }, path: { type: string } } }

'400':

components:

securitySchemes:

BearerAuth:

type: http

scheme: bearer

bearerFormat: JWT

schemas:

Error:

type: object

properties:

error: { type: string }

2706

code: { type: string }

NoteListItem:

type: object

properties:

path: { type: string }

2712

title: { type: string, nullable: true }

2713

project: { type: string, nullable: true }

2714

tags: { type: array, items: { type: string } }

2715

date: { type: string, nullable: true }

NoteFull:

type: object

properties:

path: { type: string }

2721

frontmatter: { type: object }

2722

body: { type: string }

SearchResult:

type: object

properties:

path: { type: string }

2728

snippet: { type: string }

2729

score: { type: number }

2730

project: { type: string }

2731

tags: { type: array, items: { type: string } }

NoteOutline:

type: object

required: [schema, path, headings, truncated]

properties:

schema:

type: string

enum: [knowtation.note_outline/v1]

2740

path: { type: string }

2741

title: { type: string, nullable: true }

headings:

type: array

maxItems: 500

items: { $ref: '#/components/schemas/NoteOutlineHeading' }

2746

truncated: { type: boolean }

NoteOutlineHeading:

type: object

required: [level, text, id]

2751

properties:

2752

level: { type: integer, minimum: 1, maximum: 6 }

2753

text: { type: string }

id: { type: string }

DocumentTree:

type: object

required: [schema, path, root, truncated]

properties:

schema:

type: string

enum: [knowtation.document_tree/v0]

2763

path: { type: string }

2764

title: { type: string, nullable: true }

root:

type: object

required: [children]

properties:

children:

type: array

maxItems: 500

items: { $ref: '#/components/schemas/DocumentTreeNode' }

2773

truncated: { type: boolean }

DocumentTreeNode:

type: object

required: [id, level, text, children]

2778

properties:

2779

id: { type: string }

2780

level: { type: integer, minimum: 1, maximum: 6 }

2781

text: { type: string }

2782

children:

2783

type: array

2784

items: { $ref: '#/components/schemas/DocumentTreeNode' }

MetadataFacets:

type: object

required: [schema, path, facets, inferred, truncated]

properties:

schema:

type: string

enum: [knowtation.metadata_facets/v0]

2793

path: { type: string }

2794

facets:

2795

type: object

2796

required: [project, tags, date, updated, causal_chain_id, entity, episode_id]

2797

properties:

2798

project: { type: string, nullable: true }

tags:

type: array

maxItems: 100

items: { type: string }

2803

date: { type: string, nullable: true }

2804

updated: { type: string, nullable: true }

2805

causal_chain_id: { type: string, nullable: true }

entity:

type: array

maxItems: 100

items: { type: string }

2810

episode_id: { type: string, nullable: true }

2811

inferred:

2812

type: object

2813

required: [folder, source_type]

2814

properties:

2815

folder: { type: string, nullable: true }

2816

source_type: { nullable: true, enum: [null] }

2817

truncated: { type: boolean }

SectionSource:

type: object

required: [schema, path, sections, truncated]

properties:

schema:

type: string

enum: [knowtation.section_source/v0]

2826

path: { type: string }

2827

title: { type: string, nullable: true }

2828

sections:

2829

type: array

2830

items: { $ref: '#/components/schemas/SectionSourceSection' }

2831

truncated: { type: boolean }

2832

2833

SectionSourceSection:

type: object

required:

- section_id

- heading_id

- level

- heading_path

- heading_text

- child_section_ids

- body_available

- body_returned

- snippet_returned

properties:

section_id: { type: string }

2847

heading_id: { type: string }

2848

level: { type: integer, minimum: 1, maximum: 6 }

2849

heading_path: { type: array, items: { type: string } }

2850

heading_text: { type: string }

2851

child_section_ids: { type: array, items: { type: string } }

2852

body_available: { type: boolean }

2853

body_returned: { type: boolean, enum: [false] }

2854

snippet_returned: { type: boolean, enum: [false] }

Proposal:

type: object

properties:

proposal_id: { type: string }

2860

path: { type: string }

2861

status: { type: string }

2862

intent: { type: string }

2863

base_state_id: { type: string }

2864

external_ref: { type: string }

2865

vault_id: { type: string }

2866

proposed_by: { type: string }

2867

labels: { type: array, items: { type: string } }

2868

source: { type: string }

2869

suggested_labels: { type: array, items: { type: string } }

2870

assistant_notes: { type: string }

2871

assistant_model: { type: string }

2872

assistant_at: { type: string }

2873

created_at: { type: string }

2874

updated_at: { type: string }

2875

evaluation_status:

2876

type: string

2877

enum: [none, pending, passed, failed, needs_changes]

2878

evaluation_grade: { type: string }

2879

evaluation_comment: { type: string }

2880

evaluated_by: { type: string }

2881

evaluated_at: { type: string }

evaluation_waiver:

type: object

nullable: true

properties:

by: { type: string }

at: { type: string }

reason: { type: string }

2889

review_queue: { type: string }

2890

review_severity: { type: string, enum: [standard, elevated] }

2891

auto_flag_reasons:

2892

type: array

2893

items: { type: string }

2894

auto_flag_reasons_json: { type: string, description: JSON array string on canister }

2895

review_hints: { type: string }

2896

review_hints_at: { type: string }

2897

review_hints_model: { type: string }

2898

assistant_suggested_frontmatter:

2899

type: object

2900

description: Normalized SPEC-aligned suggested note metadata from Enrich (object on GET); omitted or empty on older proposals

2901

additionalProperties: true

ProposalDetail:

allOf:

- { $ref: '#/components/schemas/Proposal' }

2906

- type: object

2907

properties:

2908

body: { type: string }

2909

frontmatter: { type: object }

2910

evaluation_checklist:

type: array

items:

type: object

properties:

id: { type: string }

label: { type: string }

2917

passed: { type: boolean }

CalendarTimeline:

type: object

required: [schema, vault_id, from, to, layers, items]

properties:

schema:

type: string

enum: [knowtation.calendar_timeline/v0]

2926

vault_id: { type: string }

2927

from: { type: string }

to: { type: string }

layers:

type: array

items:

type: string

enum: [notes, events]

items:

type: array

items:

oneOf:

- { $ref: '#/components/schemas/CalendarTimelineNoteItem' }

2939

- { $ref: '#/components/schemas/CalendarTimelineEventItem' }

2940

2941

CalendarTimelineNoteItem:

2942

type: object

2943

required: [kind, date, path, title, project, tags, sort_at]

properties:

kind:

type: string

enum: [note]

date: { type: string }

2949

path: { type: string }

2950

title: { type: string, nullable: true }

2951

project: { type: string, nullable: true }

2952

tags:

2953

type: array

2954

items: { type: string }

2955

sort_at: { type: string }

2956

2957

CalendarTimelineEventItem:

2958

type: object

2959

required: [kind, event_id, source_calendar_id, start, end, timezone, summary, busy, status, calendar_label, sort_at]

properties:

kind:

type: string

enum: [event]

event_id: { type: string }

2965

source_calendar_id: { type: string }

2966

start: { type: string }

2967

end: { type: string }

2968

timezone: { type: string }

2969

summary: { type: string, nullable: true }

2970

busy: { type: boolean }

2971

status:

2972

type: string

2973

enum: [confirmed, cancelled, tentative]

2974

calendar_label: { type: string, nullable: true }

2975

sort_at: { type: string }

2976

2977

CalendarAgentContext:

2978

type: object

2979

required: [schema, vault_id, from, to, requested_tier, effective_tier, policy_agent_context_tier_max_cap, source_calendars, items]

properties:

schema:

type: string

enum: [knowtation.calendar_agent_context/v0]

2984

vault_id: { type: string }

2985

from: { type: string }

to: { type: string }

requested_tier:

type: integer

minimum: 0

maximum: 2

effective_tier:

type: integer

minimum: 0

maximum: 2

description: Requested tier after the org policy cap is applied.

2996

policy_agent_context_tier_max_cap:

type: integer

minimum: 0

maximum: 4

source_calendars:

type: array

items: { $ref: '#/components/schemas/AgentContextCalendarSummary' }

3003

items:

3004

type: array

3005

items: { $ref: '#/components/schemas/CalendarAgentContextEventItem' }

3006

3007

AgentContextCalendarSummary:

3008

type: object

3009

required: [source_calendar_id, display_name, user_group, enabled_for_agents, agent_context_tier_max, effective_tier, event_count]

3010

properties:

3011

source_calendar_id: { type: string }

3012

display_name: { type: string }

user_group:

type: string

nullable: true

enum: [personal, work, school, other, null]

3017

enabled_for_agents: { type: boolean }

3018

agent_context_tier_max:

type: integer

minimum: 0

maximum: 4

effective_tier:

type: integer

minimum: 0

maximum: 2

event_count: { type: integer }

3027

3028

CalendarAgentContextEventItem:

3029

type: object

3030

required: [event_id, source_calendar_id, external_uid, start, end, timezone, busy, status, agent_tier]

3031

description: >

3032

Redacted event. `summary` and `calendar_label` are present only at tier 2;

3033

tier 1 omits the event title entirely.

3034

properties:

3035

event_id: { type: string }

3036

source_calendar_id: { type: string }

3037

external_uid: { type: string }

3038

start: { type: string }

3039

end: { type: string }

3040

timezone: { type: string }

3041

busy: { type: boolean }

3042

status:

3043

type: string

3044

enum: [confirmed, cancelled, tentative]

agent_tier:

type: integer

minimum: 1

maximum: 2

summary: { type: string, nullable: true }

3050

calendar_label: { type: string, nullable: true }

SourceCalendarList:

type: object

required: [schema, vault_id, source_calendars]

properties:

schema:

type: string

enum: [knowtation.source_calendars/v0]

3059

vault_id: { type: string }

3060

source_calendars:

3061

type: array

3062

items: { $ref: '#/components/schemas/SourceCalendar' }

SourceCalendar:

type: object

required: [source_calendar_id, connector_id, display_name, enabled_for_sync, enabled_for_display, enabled_for_agents, agent_context_tier_max]

3067

properties:

3068

source_calendar_id: { type: string }

3069

connector_id: { type: string }

3070

display_name: { type: string }

3071

color: { type: string, nullable: true }

user_group:

type: string

nullable: true

enum: [personal, work, school, other, null]

3076

enabled_for_sync: { type: boolean }

3077

enabled_for_display: { type: boolean }

3078

enabled_for_agents: { type: boolean }

3079

agent_context_tier_max:

type: integer

minimum: 0

maximum: 4

provider: { type: string }

3084

3085

CalendarIcsImportRequest:

type: object

required: [ics_text]

properties:

ics_text: { type: string }

3090

display_name: { type: string }

3091

source_calendar_id: { type: string }

3092

connector_id: { type: string }

3093

default_timezone: { type: string }

3094

3095

CalendarIcsImportResult:

3096

type: object

3097

required: [schema, vault_id, source_calendar_id, connector_id, imported, updated]

properties:

schema:

type: string

enum: [knowtation.calendar_import/v0]

3102

vault_id: { type: string }

3103

source_calendar_id: { type: string }

3104

connector_id: { type: string }

3105

imported: { type: integer }

3106

updated: { type: integer }

3107

3108

SourceCalendarPatchRequest:

type: object

minProperties: 1

properties:

enabled_for_display: { type: boolean }

3113

enabled_for_agents: { type: boolean }

3114

agent_context_tier_max:

type: integer

minimum: 0

maximum: 4

user_group:

type: string

nullable: true

enum: [personal, work, school, other, null]

3122

3123

SourceCalendarPatchResult:

3124

type: object

3125

required: [schema, vault_id, policy_agent_context_tier_max_cap, source_calendar]

properties:

schema:

type: string

enum: [knowtation.source_calendar_patch/v0]

3130

vault_id: { type: string }

3131

policy_agent_context_tier_max_cap:

type: integer

minimum: 0

maximum: 4

source_calendar: { $ref: '#/components/schemas/SourceCalendar' }

FlowListResponse:

type: object

required: [schema, vault_id, effective_scope, flows, truncated]

properties:

schema:

type: string

enum: [knowtation.flow_list/v0]

3144

vault_id: { type: string }

3145

effective_scope:

3146

type: string

3147

enum: [personal, project, org]

flows:

type: array

maxItems: 200

items: { $ref: '#/components/schemas/FlowSummary' }

3152

truncated: { type: boolean }

TaskListResponse:

type: object

required: [schema, vault_id, effective_scope, tasks, truncated]

properties:

schema:

type: string

enum: [knowtation.task_list/v0]

3161

vault_id: { type: string }

3162

effective_scope:

3163

type: string

3164

enum: [personal, project, org]

tasks:

type: array

maxItems: 500

items: { $ref: '#/components/schemas/TaskSummary' }

3169

truncated: { type: boolean }

3170

3171

LearningPathListResponse:

3172

type: object

3173

required: [schema, vault_id, effective_scope, paths, truncated]

properties:

schema:

type: string

enum: [knowtation.learning_path_list/v0]

3178

vault_id: { type: string }

3179

effective_scope:

3180

type: string

3181

enum: [personal, project, org]

paths:

type: array

maxItems: 200

items: { $ref: '#/components/schemas/LearningPathSummary' }

3186

truncated: { type: boolean }

LearningPathSummary:

type: object

required: [schema, path_id, scope, status, title, goal, current_step_index, step_count, next_step_title, active_decisions, workspace_id, updated]

properties:

schema:

type: string

enum: [knowtation.learning_path/v0]

3195

path_id: { type: string }

3196

scope:

3197

type: string

3198

enum: [personal, project, org]

3199

status:

3200

type: string

3201

enum: [active, paused, archived]

3202

title: { type: string }

3203

goal: { type: string }

3204

current_step_index: { type: integer }

3205

step_count: { type: integer }

3206

next_step_title: { type: string }

3207

active_decisions: { type: string }

3208

workspace_id: { type: string }

3209

updated: { type: string, format: date-time }

3210

3211

LearningPathGetResponse:

3212

type: object

3213

required: [schema, vault_id, effective_scope, path]

properties:

schema:

type: string

enum: [knowtation.learning_path_get/v0]

3218

vault_id: { type: string }

3219

effective_scope:

3220

type: string

3221

enum: [personal, project, org]

3222

path: { $ref: '#/components/schemas/LearningPathRecord' }

LearningPathRecord:

type: object

required: [schema, path_id, scope, status, title, summary, goal, steps, current_step_index, step_count, next_step_title, active_decisions, workspace_id, note_path, created, updated]

properties:

schema:

type: string

enum: [knowtation.learning_path/v0]

3231

path_id: { type: string }

3232

scope:

3233

type: string

3234

enum: [personal, project, org]

3235

status:

3236

type: string

3237

enum: [active, paused, archived]

3238

title: { type: string }

3239

summary: { type: string }

3240

goal: { type: string }

steps:

type: array

minItems: 1

maxItems: 20

items:

type: object

required: [title, objective, source_document_ids]

3248

properties:

3249

title: { type: string }

3250

objective: { type: string }

3251

source_document_ids:

3252

type: array

3253

items: { type: string }

3254

current_step_index: { type: integer }

3255

step_count: { type: integer }

3256

next_step_title: { type: string }

3257

active_decisions: { type: string }

3258

workspace_id: { type: string }

note_path:

type: string

nullable: true

created: { type: string, format: date-time }

3263

updated: { type: string, format: date-time }

3264

3265

LearningPathProposalRequest:

type: object

properties:

proposal_kind:

type: string

enum: [path_create, path_update, path_archive]

3271

title: { type: string }

3272

summary: { type: string }

3273

goal: { type: string }

3274

steps: { type: array, items: { type: object } }

3275

path_id: { type: string }

3276

intent: { type: string }

3277

3278

LearningPathProposalResponse:

3279

type: object

3280

required: [schema, proposal_id, proposal_kind, path_id, status, review_queue]

properties:

schema:

type: string

enum: [knowtation.learning_path_proposal/v0]

3285

proposal_id: { type: string }

3286

proposal_kind:

3287

type: string

3288

enum: [path_create, path_update, path_archive]

3289

path_id: { type: string }

3290

scope:

3291

type: string

3292

enum: [personal, project, org]

3293

auto_approvable: { type: boolean }

3294

status: { type: string }

3295

review_queue:

3296

type: string

3297

enum: [learning-path]

TaskSummary:

type: object

required: [schema, task_id, kind, scope, status, title, workspace_id, due_at, run_ref, truncated]

properties:

schema:

type: string

enum: [knowtation.task/v0]

3306

task_id: { type: string }

3307

kind:

3308

type: string

3309

enum: [personal, assignment, mentor_checkin, org_work_job]

3310

scope:

3311

type: string

3312

enum: [personal, project, org]

3313

status:

3314

type: string

3315

enum: [pending, in_progress, blocked, done, cancelled]

3316

title: { type: string }

3317

workspace_id: { type: string }

due_at:

type: string

nullable: true

run_ref:

type: string

nullable: true

truncated: { type: boolean }

TaskGetResponse:

type: object

required: [schema, vault_id, effective_scope, task]

properties:

schema:

type: string

enum: [knowtation.task_get/v0]

3333

vault_id: { type: string }

3334

effective_scope:

3335

type: string

3336

enum: [personal, project, org]

3337

task: { $ref: '#/components/schemas/TaskRecord' }

TaskRecord:

type: object

required:

- schema

- task_id

- kind

- scope

- status

- title

- workspace_id

- due_at

- artifact_links

- created

- updated

- truncated

properties:

schema:

type: string

enum: [knowtation.task/v0]

3358

task_id: { type: string }

3359

kind:

3360

type: string

3361

enum: [personal, assignment, mentor_checkin, org_work_job]

3362

scope:

3363

type: string

3364

enum: [personal, project, org]

3365

status:

3366

type: string

3367

enum: [pending, in_progress, blocked, done, cancelled]

3368

title: { type: string }

3369

workspace_id: { type: string }

due_at:

type: string

nullable: true

assignee_ref:

type: string

nullable: true

assigner_ref:

type: string

nullable: true

run_ref:

type: string

nullable: true

artifact_links:

type: array

maxItems: 32

items:

type: object

required: [kind, ref]

properties:

kind:

type: string

enum: [note, media, review_item]

3392

ref: { type: string }

3393

created: { type: string }

3394

updated: { type: string }

3395

truncated: { type: boolean }

3396

3397

AttachmentListResponse:

3398

type: object

3399

required: [schema, vault_id, effective_scope, attachments, truncated]

properties:

schema:

type: string

enum: [knowtation.attachment_list/v0]

3404

vault_id: { type: string }

3405

effective_scope:

3406

type: string

3407

enum: [personal, project, org]

attachments:

type: array

maxItems: 500

items: { $ref: '#/components/schemas/AttachmentSummary' }

3412

truncated: { type: boolean }

AttachmentSummary:

type: object

required:

- schema

- attachment_id

- source

- storage_kind

- mime_class

- scope

- display_label

- created

- truncated

properties:

schema:

type: string

enum: [knowtation.attachment/v0]

3430

attachment_id: { type: string }

3431

source:

3432

type: string

3433

enum: [vault_file, mist_blob, embedded_url]

3434

storage_kind:

3435

type: string

3436

enum: [vault_blob, external_link]

3437

mime_class:

3438

type: string

3439

enum: [image, video, audio, document, unknown]

3440

scope:

3441

type: string

3442

enum: [personal, project, org]

3443

display_label: { type: string }

3444

created: { type: string }

3445

truncated: { type: boolean }

3446

3447

AttachmentGetResponse:

3448

type: object

3449

required: [schema, vault_id, effective_scope, attachment]

properties:

schema:

type: string

enum: [knowtation.attachment_get/v0]

3454

vault_id: { type: string }

3455

effective_scope:

3456

type: string

3457

enum: [personal, project, org]

3458

attachment: { $ref: '#/components/schemas/AttachmentRecord' }

3459

3460

MediaProposalResponse:

3461

type: object

3462

required: [schema, proposal_id, proposal_kind, attachment_id, scope, auto_approvable, status]

properties:

schema:

type: string

enum: [knowtation.media_proposal/v0]

3467

proposal_id: { type: string }

3468

proposal_kind:

3469

type: string

3470

enum: [media_external_link, media_attach]

3471

attachment_id:

3472

type: string

3473

pattern: '^att_(file|mist|url|link)_[a-f0-9]{32}$'

3474

note_ref: { type: [string, 'null'] }

3475

connector_id: { type: [string, 'null'] }

3476

scope:

3477

type: string

3478

enum: [personal, project, org]

3479

base_state_id: { type: string }

3480

external_ref: { type: [string, 'null'] }

auto_approvable:

type: boolean

enum: [false]

status:

type: string

enum: [proposed]

review_queue:

type: string

enum: [media-writes]

AttachmentRecord:

type: object

required:

- schema

- attachment_id

- source

- storage_kind

- mime_class

- mime_type

- scope

- display_label

- byte_size

- linked_note_refs

- agent_visible

- created

- updated

- truncated

properties:

schema:

type: string

enum: [knowtation.attachment/v0]

3512

attachment_id: { type: string }

3513

source:

3514

type: string

3515

enum: [vault_file, mist_blob, embedded_url]

3516

storage_kind:

3517

type: string

3518

enum: [vault_blob, external_link]

3519

mime_class:

3520

type: string

3521

enum: [image, video, audio, document, unknown]

mime_type:

type: string

nullable: true

scope:

type: string

enum: [personal, project, org]

3528

display_label: { type: string }

byte_size:

type: integer

nullable: true

linked_note_refs:

type: array

items: { type: string }

3535

agent_visible: { type: boolean }

3536

created: { type: string }

3537

updated: { type: string }

3538

truncated: { type: boolean }

3539

3540

TaskWriteProposalRequest:

type: object

required: [intent]

properties:

proposal_kind:

type: string

enum: [task_create, task_status_update, task_assign, task_artifact_link]

3547

intent: { type: string, minLength: 1 }

3548

task: { $ref: '#/components/schemas/TaskRecord' }

3549

task_id: { type: string }

3550

base_state_id: { type: string }

3551

status:

3552

type: string

3553

enum: [pending, in_progress, blocked, done, cancelled]

3554

assignee_ref: { type: string, nullable: true }

3555

assigner_ref: { type: string, nullable: true }

3556

artifact_link:

3557

type: object

3558

required: [kind, ref]

3559

properties:

3560

kind: { type: string }

3561

ref: { type: string }

3562

3563

TaskLoopWriteProposalRequest:

type: object

required: [intent]

properties:

proposal_kind:

type: string

enum: [task_loop_create, task_loop_pause, task_loop_cancel]

3570

intent: { type: string, minLength: 1 }

3571

loop: { type: object }

3572

loop_id: { type: string }

3573

base_state_id: { type: string }

3574

3575

TaskInstanceMaterializeRequest:

type: object

required: [intent]

properties:

intent: { type: string, minLength: 1 }

3580

occurrence_key: { type: string }

3581

occurrence_at: { type: string }

3582

due_at: { type: string }

3583

title_override: { type: string }

3584

base_state_id: { type: string }

3585

3586

TaskProposalResponse:

type: object

required:

- schema

- proposal_id

- proposal_kind

- auto_approvable

- status

- review_queue

properties:

schema:

type: string

enum: [knowtation.task_proposal/v0]

3599

proposal_id: { type: string }

3600

proposal_kind: { type: string }

3601

task_id: { type: string, nullable: true }

3602

loop_id: { type: string, nullable: true }

3603

base_state_id: { type: string, nullable: true }

3604

scope:

3605

type: string

3606

enum: [personal, project, org]

3607

auto_approvable: { type: boolean }

3608

status: { type: string }

3609

review_queue: { type: string }

3610

3611

TaskInstanceProposalResponse:

3612

allOf:

3613

- $ref: '#/components/schemas/TaskProposalResponse'

3614

- type: object

3615

required: [occurrence_key]

properties:

schema:

type: string

enum: [knowtation.task_instance_proposal/v0]

3620

occurrence_key: { type: string }

FlowSummary:

type: object

required: [schema, flow_id, title, version, scope, summary, tags, step_count, updated, truncated]

properties:

schema:

type: string

enum: [knowtation.flow/v0]

3629

flow_id: { type: string }

3630

title: { type: string }

3631

version: { type: string }

3632

scope:

3633

type: string

3634

enum: [personal, project, org]

3635

summary: { type: string }

tags:

type: array

maxItems: 32

items: { type: string }

3640

step_count: { type: integer, minimum: 0 }

3641

updated: { type: string }

3642

truncated: { type: boolean }

FlowGetResponse:

type: object

required: [schema, vault_id, flow, steps]

properties:

schema:

type: string

enum: [knowtation.flow_get/v0]

3651

vault_id: { type: string }

3652

flow: { $ref: '#/components/schemas/Flow' }

steps:

type: array

maxItems: 100

items: { $ref: '#/components/schemas/FlowStep' }

FlowRun:

type: object

required:

[schema, run_id, run_ref, flow_id, flow_version, scope, status, step_states, started, provenance]

3662

description: knowtation.flow_run/v0 — canonical run state (pointer-only).

properties:

schema:

type: string

enum: [knowtation.flow_run/v0]

3667

run_id: { type: string }

3668

run_ref:

3669

type: string

3670

description: Portable cross-system pointer (flow_run:…); resolves get/list lookups.

3671

flow_id: { type: string }

3672

flow_version: { type: string }

3673

scope:

3674

type: string

3675

enum: [personal, project, org]

3676

status:

3677

type: string

3678

enum: [pending, in_progress, blocked, done, abandoned]

step_states:

type: array

maxItems: 200

items:

type: object

required: [step_id, status, verified]

3685

properties:

3686

step_id: { type: string }

3687

status:

3688

type: string

3689

enum: [pending, in_progress, blocked, done, skipped]

3690

evidence_ref: { type: string, nullable: true }

3691

verified: { type: boolean }

3692

started: { type: string, format: date-time }

3693

provenance:

3694

type: object

3695

required: [actor, harness]

3696

properties:

3697

actor: { type: string, description: Hashed actor id only }

3698

harness: { type: string }

3699

task_ref: { type: string, nullable: true }

3700

external_ref: { type: string, nullable: true }

FlowRunGetResponse:

type: object

required: [schema, vault_id, run]

properties:

schema:

type: string

enum: [knowtation.flow_run_get/v0]

3709

vault_id: { type: string }

3710

run: { $ref: '#/components/schemas/FlowRun' }

FlowRunResponse:

allOf:

- $ref: '#/components/schemas/FlowRunGetResponse'

FlowRunListResponse:

type: object

required: [schema, vault_id, effective_scope, runs, truncated]

properties:

schema:

type: string

enum: [knowtation.flow_run_list/v0]

3723

vault_id: { type: string }

3724

effective_scope:

3725

type: string

3726

enum: [personal, project, org]

runs:

type: array

maxItems: 200

items: { $ref: '#/components/schemas/FlowRun' }

3731

truncated: { type: boolean }

3732

3733

FlowRunStartResponse:

3734

type: object

3735

required: [schema, run]

properties:

schema:

type: string

enum: [knowtation.flow_run_start/v0]

3740

run: { $ref: '#/components/schemas/FlowRun' }

3741

3742

FlowRunSubmitReviewResponse:

3743

type: object

3744

required: [schema, run, proposal_id]

properties:

schema:

type: string

enum: [knowtation.flow_run_submit_review/v0]

3749

run: { $ref: '#/components/schemas/FlowRun' }

3750

proposal_id: { type: string }

FlowProposeRequest:

type: object

required: [flow, steps, intent]

3755

description: Propose a new Flow. intent is untrusted and recorded verbatim.

3756

properties:

3757

flow: { $ref: '#/components/schemas/Flow' }

steps:

type: array

maxItems: 100

items: { $ref: '#/components/schemas/FlowStep' }

3762

intent: { type: string, minLength: 1 }

3763

3764

FlowProposeEditRequest:

3765

type: object

3766

required: [flow, steps, intent, base_version, base_state_id]

3767

description: >

3768

Propose an edit. base_version + base_state_id (flowst1_ token) gate

3769

optimistic concurrency; flow.version must exceed base_version.

3770

properties:

3771

flow: { $ref: '#/components/schemas/Flow' }

steps:

type: array

maxItems: 100

items: { $ref: '#/components/schemas/FlowStep' }

3776

intent: { type: string, minLength: 1 }

3777

base_version: { type: string }

3778

base_state_id: { type: string }

FlowImportRequest:

type: object

required: [bundle, intent]

3783

description: Import a portable bundle through the same scope-checked propose path.

properties:

bundle:

type: object

required: [flow, steps]

3788

properties:

3789

flow: { $ref: '#/components/schemas/Flow' }

steps:

type: array

maxItems: 100

items: { $ref: '#/components/schemas/FlowStep' }

3794

intent: { type: string, minLength: 1 }

3795

external_ref: { type: string }

3796

source_vault_hint: { type: string }

3797

3798

FlowProposalResponse:

3799

type: object

3800

required: [schema, proposal_id, flow_id, scope, auto_approvable, status, review_queue]

3801

description: >

3802

knowtation.flow_proposal/v0 envelope — pointers/labels only, never a

3803

rendered Flow body or secret. base_version/base_state_id are null for new.

properties:

schema:

type: string

enum: [knowtation.flow_proposal/v0]

3808

proposal_id: { type: string }

3809

flow_id: { type: string }

3810

base_version: { type: string, nullable: true }

3811

base_state_id: { type: string, nullable: true }

3812

scope:

3813

type: string

3814

enum: [personal, project, org]

3815

auto_approvable: { type: boolean }

status:

type: string

enum: [proposed]

review_queue: { type: string }

3820

3821

FlowExternalGrantMintRequest:

3822

type: object

3823

required: [flow_version, requested_tools]

3824

properties:

3825

flow_version: { type: string }

requested_tools:

type: array

minItems: 1

items: { type: string }

3830

ttl_seconds: { type: integer, minimum: 1 }

3831

actor_label: { type: string }

FlowExternalGrant:

type: object

required:

- schema

- grant_id

- vault_id

- scope

- flow_id

- flow_version

- allowed_tools

- allowed_harnesses

- expires_at

- issued_at

- revoked_at

- actor_hash

- invocation_count

properties:

schema:

type: string

enum: [knowtation.flow_external_grant/v0]

3853

grant_id: { type: string }

3854

vault_id: { type: string }

3855

scope:

3856

type: string

3857

enum: [personal, project, org]

3858

flow_id: { type: string }

3859

flow_version: { type: string }

3860

allowed_tools:

3861

type: array

3862

items: { type: string }

3863

allowed_harnesses:

3864

type: array

3865

items: { type: string }

3866

expires_at: { type: string, format: date-time }

3867

issued_at: { type: string, format: date-time }

3868

revoked_at: { type: string, format: date-time, nullable: true }

3869

actor_hash: { type: string }

3870

max_invocations: { type: integer }

3871

invocation_count: { type: integer }

3872

3873

FlowExternalGrantMintResponse:

3874

type: object

3875

required: [schema, grant, bearer, expires_at]

properties:

schema:

type: string

enum: [knowtation.flow_external_grant_mint/v0]

3880

grant: { $ref: '#/components/schemas/FlowExternalGrant' }

3881

bearer: { type: string }

3882

expires_at: { type: string, format: date-time }

3883

3884

FlowExternalGrantListResponse:

3885

type: object

3886

required: [schema, vault_id, grants]

properties:

schema:

type: string

enum: [knowtation.flow_external_grant_list/v0]

3891

vault_id: { type: string }

3892

grants:

3893

type: array

3894

items: { $ref: '#/components/schemas/FlowExternalGrant' }

3895

3896

AgentIdentityRegisterRequest:

type: object

required: [kind]

properties:

kind:

type: string

enum: [user_owned, org_owned, delegate]

3903

agent_id: { type: string }

3904

label: { type: string }

3905

scope_ceiling:

3906

type: string

3907

enum: [personal, project, org]

3908

3909

DelegationProposalResponse:

3910

type: object

3911

required: [schema, proposal_id, intent]

properties:

schema:

type: string

enum: [knowtation.delegation_proposal/v0]

3916

proposal_id: { type: string }

3917

intent: { type: string }

3918

agent_id: { type: string }

3919

consent_id: { type: string }

AgentIdentity:

type: object

required:

- schema

- agent_id

- kind

- owner_ref

- vault_id

- scope_ceiling

- status

- created

- updated

properties:

schema:

type: string

enum: [knowtation.agent_identity/v0]

3937

agent_id: { type: string }

3938

kind:

3939

type: string

3940

enum: [user_owned, org_owned, delegate]

3941

owner_ref: { type: string }

3942

vault_id: { type: string }

3943

scope_ceiling:

3944

type: string

3945

enum: [personal, project, org]

3946

label: { type: string }

3947

status:

3948

type: string

3949

enum: [active, suspended, revoked]

3950

created: { type: string, format: date-time }

3951

updated: { type: string, format: date-time }

3952

3953

AgentIdentityListResponse:

3954

type: object

3955

required: [schema, vault_id, identities]

properties:

schema:

type: string

enum: [knowtation.agent_identity_list/v0]

3960

vault_id: { type: string }

3961

identities:

3962

type: array

3963

items: { $ref: '#/components/schemas/AgentIdentity' }

3964

3965

DelegationConsentProposeRequest:

3966

type: object

3967

required: [delegate_agent_id, scope]

3968

properties:

3969

delegate_agent_id: { type: string }

3970

scope:

3971

type: string

3972

enum: [personal, project, org]

3973

workspace_id: { type: string }

3974

allowed_flow_ids:

3975

type: array

3976

items: { type: string }

3977

allowed_task_kinds:

3978

type: array

3979

items: { type: string }

3980

allowed_task_ids:

3981

type: array

3982

items: { type: string }

3983

expires_at: { type: string, format: date-time }

3984

3985

DelegationConsentProposeResponse:

3986

type: object

3987

required: [schema, proposal_id, intent, consent_id]

properties:

schema:

type: string

enum: [knowtation.delegation_proposal/v0]

3992

proposal_id: { type: string }

3993

intent: { type: string }

3994

consent_id: { type: string }

3995

consent_preview: { $ref: '#/components/schemas/DelegationConsent' }

DelegationConsent:

type: object

required:

- schema

- consent_id

- principal_ref

- delegate_agent_id

- scope

- revoked_at

- evidence_ref

- created

properties:

schema:

type: string

enum: [knowtation.delegation_consent/v0]

4012

consent_id: { type: string }

4013

principal_ref: { type: string }

4014

delegate_agent_id: { type: string }

4015

scope:

4016

type: string

4017

enum: [personal, project, org]

4018

workspace_id: { type: string }

4019

allowed_flow_ids:

4020

type: array

4021

items: { type: string }

4022

allowed_task_kinds:

4023

type: array

4024

items: { type: string }

4025

allowed_task_ids:

4026

type: array

4027

items: { type: string }

4028

expires_at: { type: string, format: date-time }

4029

revoked_at: { type: string, format: date-time, nullable: true }

4030

evidence_ref: { type: string }

4031

created: { type: string, format: date-time }

4032

4033

DelegationGrantMintRequest:

4034

type: object

4035

required: [consent_id, actor_agent_id]

4036

properties:

4037

consent_id: { type: string }

4038

actor_agent_id: { type: string }

4039

task_ref: { type: string }

4040

run_ref: { type: string }

4041

flow_id: { type: string }

4042

flow_version: { type: string }

4043

ttl_seconds: { type: integer, minimum: 1 }

DelegationGrant:

type: object

required:

- schema

- grant_id

- consent_id

- actor_agent_id

- principal_ref

- scope

- expires_at

- revoked_at

- action_count

- issued_at

properties:

schema:

type: string

enum: [knowtation.delegation_grant/v0]

4062

grant_id: { type: string }

4063

consent_id: { type: string }

4064

actor_agent_id: { type: string }

4065

principal_ref: { type: string }

4066

scope:

4067

type: string

4068

enum: [personal, project, org]

4069

workspace_id: { type: string }

4070

task_ref: { type: string }

4071

run_ref: { type: string }

4072

flow_id: { type: string }

4073

flow_version: { type: string }

4074

expires_at: { type: string, format: date-time }

4075

revoked_at: { type: string, format: date-time, nullable: true }

4076

max_actions: { type: integer }

4077

action_count: { type: integer }

4078

issued_at: { type: string, format: date-time }

4079

4080

DelegationGrantMintResponse:

4081

type: object

4082

required: [schema, grant, bearer, expires_at]

properties:

schema:

type: string

enum: [knowtation.delegation_grant_mint/v0]

4087

grant: { $ref: '#/components/schemas/DelegationGrant' }

4088

bearer: { type: string }

4089

expires_at: { type: string, format: date-time }

4090

4091

DelegationGrantListResponse:

4092

type: object

4093

required: [schema, vault_id, grants]

properties:

schema:

type: string

enum: [knowtation.delegation_grant_list/v0]

4098

vault_id: { type: string }

4099

grants:

4100

type: array

4101

items: { $ref: '#/components/schemas/DelegationGrant' }

4102

4103

DelegationAuditAppendRequest:

4104

type: object

4105

required: [grant_id, actor_agent_id, action, evidence_refs]

4106

properties:

4107

grant_id: { type: string }

4108

actor_agent_id: { type: string }

4109

principal_ref: { type: string }

4110

action:

4111

type: string

4112

enum: [advance_step, complete_task, propose_outcome, invoke_tool, mint_subgrant]

evidence_refs:

type: array

minItems: 1

items: { type: string }

4117

task_ref: { type: string }

4118

run_ref: { type: string }

4119

flow_id: { type: string }

4120

flow_version: { type: string }

4121

step_id: { type: string }

4122

execution_location:

4123

type: string

4124

enum: [local, hosted, hybrid]

DelegationAudit:

type: object

required:

- schema

- audit_id

- grant_id

- actor_agent_id

- principal_ref

- action

- evidence_refs

- occurred_at

properties:

schema:

type: string

enum: [knowtation.delegation_audit/v0]

4141

audit_id: { type: string }

4142

grant_id: { type: string }

4143

actor_agent_id: { type: string }

4144

principal_ref: { type: string }

4145

task_ref: { type: string }

4146

run_ref: { type: string }

4147

flow_id: { type: string }

4148

flow_version: { type: string }

4149

step_id: { type: string }

4150

action:

4151

type: string

4152

enum: [advance_step, complete_task, propose_outcome, invoke_tool, mint_subgrant]

4153

evidence_refs:

4154

type: array

4155

items: { type: string }

4156

occurred_at: { type: string, format: date-time }

4157

execution_location:

4158

type: string

4159

enum: [local, hosted, hybrid]

FlowProjectResponse:

type: object

required: [schema, vault_id, projection, staleness, generator]

properties:

schema:

type: string

enum: [knowtation.flow_project/v0]

4168

vault_id: { type: string }

4169

projection: { $ref: '#/components/schemas/FlowProjection' }

4170

staleness: { $ref: '#/components/schemas/FlowProjectionStaleness' }

4171

generator: { $ref: '#/components/schemas/FlowProjectionGenerator' }

FlowProjection:

type: object

required: [schema, flow_id, flow_version, harness, rendered, generated_from_canonical, editable]

properties:

schema:

type: string

enum: [knowtation.flow_projection/v0]

4180

flow_id: { type: string }

4181

flow_version: { type: string }

4182

harness:

4183

type: string

4184

enum: [cursor_rule, cursor_skill, mcp_prompt, cli_runbook, agent_bundle]

rendered:

type: string

maxLength: 65536

generated_from_canonical:

type: boolean

enum: [true]

editable:

type: boolean

enum: [false]

fidelity:

type: object

required: [dropped_fields]

properties:

dropped_fields:

type: array

items: { type: string }

4201

notes: { type: string }

4202

4203

FlowProjectionStaleness:

4204

type: object

4205

required: [stale, projection_version, latest_version]

4206

properties:

4207

stale: { type: boolean }

4208

projection_version: { type: string }

4209

latest_version: { type: string }

4210

4211

FlowProjectionGenerator:

4212

type: object

4213

required: [generator_version, content_hash, generated_at]

4214

properties:

4215

generator_version: { type: string }

4216

content_hash: { type: string }

4217

generated_at: { type: string }

Flow:

type: object

required: [schema, flow_id, title, version, scope, summary, steps, updated, truncated]

properties:

schema:

type: string

enum: [knowtation.flow/v0]

4226

flow_id: { type: string }

4227

title: { type: string }

4228

version: { type: string }

4229

scope:

4230

type: string

4231

enum: [personal, project, org]

4232

summary: { type: string }

tags:

type: array

maxItems: 32

items: { type: string }

steps:

type: array

maxItems: 100

items: { type: string }

inputs:

type: array

items:

type: object

required: [name, type, required]

4246

properties:

4247

4248

type: { type: string }

4249

required: { type: boolean }

4250

vault_mirror_path: { type: string, nullable: true }

4251

updated: { type: string }

4252

truncated: { type: boolean }

FlowStep:

type: object

required: [schema, step_id, flow_id, ordinal, owned_job, instruction, trigger, when_not_to_run, boundaries, output_shape, verification, automatable]

properties:

schema:

type: string

enum: [knowtation.flow_step/v0]

4261

step_id: { type: string }

4262

flow_id: { type: string }

4263

ordinal: { type: integer, minimum: 1 }

4264

owned_job: { type: string }

4265

instruction: { type: string }

4266

trigger: { type: string }

4267

when_not_to_run: { type: string }

requires:

type: array

items:

type: object

required: [kind, id]

properties:

kind:

type: string

enum: [vault_scope, tool, file, artifact]

id: { type: string }

boundaries:

type: array

items: { type: string }

skill_refs:

type: array

items:

type: object

required: [kind, id]

properties:

kind:

type: string

enum: [mcp_prompt, skill_pack, cli, external_tool]

id: { type: string }

inputs:

type: array

items:

type: object

required: [name, from]

4296

properties:

4297

4298

from: { type: string }

outputs:

type: array

items:

type: object

required: [name, type]

4304

properties:

4305

4306

type: { type: string }

4307

output_shape: { type: string }

4308

verification:

4309

type: object

4310

required: [kind, evidence_required, description]

properties:

kind:

type: string

enum: [human_review, artifact_exists, value_match, test_pass, agent_check]

4315

evidence_required: { type: boolean }

4316

description: { type: string }

4317

automatable:

4318

type: string

4319

enum: [manual, agent_assisted, automatable]