{ "openapi": "3.1.0", "info": { "title": "Harken Notes API", "version": "5", "description": "Direct HTTPS API for Harken notes, collections, search, change feed, transcripts, assets, export, and scoped API keys. Base path is /api/v5. Authenticate with a scoped hk_ API key, a signed-in native Harken session, or an OAuth 2.1 access token whose resource and audience are exactly https://harken.hemisthia.com/api/v5. OAuth grants do not include asset scopes. GET /api/v5/health is public. Authenticated GET /api/v5/export is exempt from the paid entitlement gate. Other /api/v5 routes require an active Harken Pro entitlement after authentication.", "contact": { "email": "hello@hemisthia.com" } }, "servers": [ { "url": "https://harken.hemisthia.com" } ], "tags": [ { "name": "Health" }, { "name": "Notes" }, { "name": "Collections" }, { "name": "Changes" }, { "name": "Transcripts" }, { "name": "Assets" }, { "name": "Export" }, { "name": "API keys" } ], "paths": { "/api/v5/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Public schema health", "description": "Unauthenticated. Returns the Notes API schema version.", "security": [], "responses": { "200": { "description": "API is reachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v5/notes": { "get": { "operationId": "listNotes", "tags": [ "Notes" ], "summary": "List note metadata", "description": "Markdown bodies are omitted. Use owner-bound cursor pagination.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Page of note metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } }, "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Kind" }, { "$ref": "#/components/parameters/CollectionID" }, { "$ref": "#/components/parameters/IncludeDeleted" } ] }, "post": { "operationId": "createNote", "tags": [ "Notes" ], "summary": "Create a note", "description": "Requires Idempotency-Key. kind is required (scroll or meeting). title and markdown default to empty strings. Meeting notes require properties.meeting; scroll notes must omit it.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "201": { "description": "Note created.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" } } } } } }, "/api/v5/notes/search": { "get": { "operationId": "searchNotes", "tags": [ "Notes" ], "summary": "Search notes", "description": "Full-text search. Response is results: [{note, snippet}], snapshotSequence, and nextCursor.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Search hits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteSearchResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ] } }, "/api/v5/notes/{id}": { "get": { "operationId": "getNote", "tags": [ "Notes" ], "summary": "Read a note", "description": "JSON by default. Send Accept text/markdown for YAML front-matter plus body.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Note JSON or Markdown.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } }, "text/markdown": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" } ] }, "patch": { "operationId": "patchNote", "tags": [ "Notes" ], "summary": "Update a note", "description": "Requires If-Match and Idempotency-Key.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Updated note.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotePatch" } } } } }, "delete": { "operationId": "deleteNote", "tags": [ "Notes" ], "summary": "Delete a note", "description": "Requires If-Match and Idempotency-Key.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:delete" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Deleted note metadata.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v5/notes/{id}/backlinks": { "get": { "operationId": "listNoteBacklinks", "tags": [ "Notes" ], "summary": "List backlinks", "description": "Notes that link to this note.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Backlink page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BacklinkListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ] } }, "/api/v5/notes/{id}/restore": { "post": { "operationId": "restoreNote", "tags": [ "Notes" ], "summary": "Restore a deleted note", "description": "Requires If-Match and Idempotency-Key.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Restored note.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v5/notes/{id}/transcript": { "get": { "operationId": "getTranscript", "tags": [ "Transcripts" ], "summary": "Read a meeting transcript", "description": "Requires meetings:read. Offset pagination: offset, limit, turns, nextOffset, total. No cursor.", "security": [ { "apiKey": [] }, { "oauth2": [ "meetings:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Transcript turns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptReadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/Limit" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ] }, "post": { "operationId": "appendTranscript", "tags": [ "Transcripts" ], "summary": "Append transcript turns", "description": "Requires notes:write and Idempotency-Key. Does not use If-Match. Request turns accept only index, speaker, text, startMs, and endMs. noteID and createdAt are response-only and rejected on input.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Count of appended turns and the new total.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptAppendResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptAppend" } } } } } }, "/api/v5/notes/{id}/assets": { "post": { "operationId": "uploadNoteAsset", "tags": [ "Assets" ], "summary": "Upload a note asset", "description": "Multipart field asset. Requires assets:write, If-Match, and Idempotency-Key. OAuth tokens cannot grant asset scopes.", "security": [ { "apiKey": [] }, { "nativeSession": [] } ], "responses": { "201": { "description": "Asset attached. Body includes note and asset. Note ETag is returned.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/NoteID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "asset" ], "properties": { "asset": { "type": "string", "format": "binary" }, "assetID": { "type": "string", "format": "uuid" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "purpose": { "type": "string" } } } } } } } }, "/api/v5/changes": { "get": { "operationId": "listChanges", "tags": [ "Changes" ], "summary": "Read the change feed", "description": "Pass since=genesis for the first page (required), then the returned cursor as since. include=bodies inlines resources when they fit.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Change page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } }, "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string" }, "description": "genesis or a previous change cursor." }, { "$ref": "#/components/parameters/Limit" }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "bodies" ] } } ] } }, "/api/v5/collections": { "get": { "operationId": "listCollections", "tags": [ "Collections" ], "summary": "List collections", "description": "Owner-bound cursor pagination.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Collection page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } }, "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IncludeDeleted" } ] }, "post": { "operationId": "createCollection", "tags": [ "Collections" ], "summary": "Create a collection", "description": "Requires Idempotency-Key.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "201": { "description": "Collection created.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreate" } } } } } }, "/api/v5/collections/{id}": { "get": { "operationId": "getCollection", "tags": [ "Collections" ], "summary": "Read a collection", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Collection.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "$ref": "#/components/parameters/CollectionPathID" } ] }, "patch": { "operationId": "patchCollection", "tags": [ "Collections" ], "summary": "Update a collection", "description": "Requires If-Match and Idempotency-Key. Body may include name, parentID, and sortOrder.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Updated collection.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/CollectionPathID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionPatch" } } } } }, "delete": { "operationId": "deleteCollection", "tags": [ "Collections" ], "summary": "Delete a collection", "description": "Requires If-Match and Idempotency-Key.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:delete" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Deleted collection.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/CollectionPathID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v5/collections/{id}/restore": { "post": { "operationId": "restoreCollection", "tags": [ "Collections" ], "summary": "Restore a deleted collection", "description": "Requires If-Match and Idempotency-Key.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:write" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Restored collection.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/CollectionPathID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v5/assets/{assetID}": { "get": { "operationId": "downloadAsset", "tags": [ "Assets" ], "summary": "Download an asset", "description": "Requires assets:read. Bytes use a hash ETag. Pass meta=1 for JSON metadata whose version ETag is required by DELETE. OAuth tokens cannot grant this scope.", "security": [ { "apiKey": [] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Raw asset bytes, or JSON metadata when meta=1.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "$ref": "#/components/parameters/AssetID" }, { "name": "meta", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "When 1, return JSON asset metadata and a version ETag instead of bytes." } ] }, "delete": { "operationId": "deleteAsset", "tags": [ "Assets" ], "summary": "Delete an asset", "description": "Requires assets:write, If-Match of the meta=1 version ETag, and Idempotency-Key. The bytes hash ETag cannot be used here. OAuth tokens cannot grant this scope.", "security": [ { "apiKey": [] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Deleted asset metadata.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/VersionConflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } }, "parameters": [ { "$ref": "#/components/parameters/AssetID" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v5/export": { "get": { "operationId": "exportNotes", "tags": [ "Export" ], "summary": "Export notes as a zip", "description": "Authenticated notes:read. Exempt from the paid entitlement gate. One request per 10 minutes per owner.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Zip archive.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v5/account/api-keys": { "get": { "operationId": "listApiKeys", "tags": [ "API keys" ], "summary": "List API keys", "description": "Requires notes:read. Secrets are never returned. API keys, OAuth tokens with notes:read, and native sessions may list keys.", "security": [ { "apiKey": [] }, { "oauth2": [ "notes:read" ] }, { "nativeSession": [] } ], "responses": { "200": { "description": "Key metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } }, "post": { "operationId": "issueApiKey", "tags": [ "API keys" ], "summary": "Issue an API key", "description": "Native Harken session only, plus notes:write. Requires Idempotency-Key. The secret is returned once; replays omit it.", "security": [ { "nativeSession": [] } ], "responses": { "201": { "description": "Issued key, including secret on first success.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssueResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/SessionRequired" }, "409": { "$ref": "#/components/responses/Conflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssue" } } } } } }, "/api/v5/account/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "tags": [ "API keys" ], "summary": "Revoke an API key", "description": "Native Harken session only, plus notes:delete. Requires Idempotency-Key. Does not use If-Match. Keys do not expire; revoke to stop authentication.", "security": [ { "nativeSession": [] } ], "responses": { "200": { "description": "Revoked key id and timestamp.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRevokeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/SessionRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "hk_", "description": "Scoped Notes API key issued in the Mac app. Prefix hk_." }, "nativeSession": { "type": "http", "scheme": "bearer", "description": "Signed-in Harken app session. Required to issue or revoke API keys." }, "oauth2": { "type": "oauth2", "description": "Better Auth OAuth 2.1. Resource and audience must be exactly https://harken.hemisthia.com/api/v5.", "flows": { "authorizationCode": { "authorizationUrl": "https://harken.hemisthia.com/api/better-auth/oauth2/authorize", "tokenUrl": "https://harken.hemisthia.com/api/better-auth/oauth2/token", "scopes": { "offline_access": "Refresh tokens.", "notes:read": "List, search, export, and read notes.", "notes:write": "Create and update notes and collections.", "notes:delete": "Delete notes and collections.", "meetings:read": "Read meeting transcripts." } } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Owner-bound opaque cursor from a previous page." }, "Kind": { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "scroll", "meeting" ] } }, "CollectionID": { "name": "collectionID", "in": "query", "schema": { "type": "string", "format": "uuid" } }, "IncludeDeleted": { "name": "includeDeleted", "in": "query", "schema": { "type": "boolean" } }, "NoteID": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "CollectionPathID": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "AssetID": { "name": "assetID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted version ETag from the last read of that resource. Required on PATCH, DELETE, restore, and asset writes. Not used for API-key revoke or transcript append. Asset DELETE requires the meta=1 version ETag, not the bytes hash ETag." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Required on mutations, including API-key issue and revoke and transcript append. Same owner, operation, key, and body replays the original response." } }, "headers": { "ETag": { "description": "Quoted resource version.", "schema": { "type": "string" } }, "IdempotencyReplayed": { "description": "true when this response is an idempotent replay.", "schema": { "type": "string", "enum": [ "true" ] } } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": [ "ok", "schemaVersion" ], "properties": { "ok": { "type": "boolean", "const": true }, "schemaVersion": { "type": "integer", "const": 5 } } }, "HealthResponse": { "type": "object", "required": [ "ok", "schemaVersion" ], "properties": { "ok": { "type": "boolean", "const": true }, "schemaVersion": { "type": "integer", "const": 5 } } }, "Error": { "type": "object", "required": [ "ok", "error", "code" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" }, "retryable": { "type": "boolean" }, "checkoutURL": { "type": [ "string", "null" ] } } }, "Note": { "type": "object", "required": [ "id", "kind", "title", "version", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "scroll", "meeting" ] }, "title": { "type": "string" }, "markdown": { "type": "string" }, "properties": { "type": "object" }, "collectionID": { "type": [ "string", "null" ], "format": "uuid" }, "parentID": { "type": [ "string", "null" ], "format": "uuid" }, "sortOrder": { "type": "number" }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "NoteCreate": { "type": "object", "required": [ "kind" ], "description": "kind is required (scroll or meeting). title and markdown default to empty strings. Meeting notes require properties.meeting. Scroll notes must omit properties.meeting.", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "scroll", "meeting" ] }, "title": { "type": "string" }, "markdown": { "type": "string" }, "properties": { "type": "object", "properties": { "meeting": { "type": "object", "description": "Required when kind is meeting; forbidden when kind is scroll." } }, "additionalProperties": true }, "collectionID": { "type": [ "string", "null" ], "format": "uuid" }, "parentID": { "type": [ "string", "null" ], "format": "uuid" }, "sortOrder": { "type": "number" } } }, "NotePatch": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string" }, "markdown": { "type": "string" }, "appendMarkdown": { "type": "string" }, "properties": { "type": "object" }, "collectionID": { "type": [ "string", "null" ], "format": "uuid" }, "parentID": { "type": [ "string", "null" ], "format": "uuid" }, "sortOrder": { "type": "number" }, "expectedGeneratedBodyHash": { "type": "string" } } }, "NoteResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/Note" } } } ] }, "NoteListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "notes" ], "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "snapshotSequence": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } } } ] }, "NoteSearchResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "note", "snippet" ], "properties": { "note": { "$ref": "#/components/schemas/Note" }, "snippet": { "type": "string" } } } }, "snapshotSequence": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } } } ] }, "BacklinkListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "backlinks" ], "properties": { "backlinks": { "type": "array", "items": { "type": "object", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/Note" } } } }, "snapshotSequence": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } } } ] }, "Collection": { "type": "object", "required": [ "id", "name", "version", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "parentID": { "type": [ "string", "null" ], "format": "uuid" }, "sortOrder": { "type": "number" }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "CollectionCreate": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "parentID": { "type": [ "string", "null" ], "format": "uuid" }, "sortOrder": { "type": "number" } } }, "CollectionPatch": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string" }, "parentID": { "type": [ "string", "null" ], "format": "uuid" }, "sortOrder": { "type": "number" } } }, "CollectionResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "collection" ], "properties": { "collection": { "$ref": "#/components/schemas/Collection" } } } ] }, "CollectionListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "collections" ], "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "snapshotSequence": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] } } } ] }, "Change": { "type": "object", "required": [ "sequence", "resourceType", "resourceID", "action", "version", "changedAt" ], "properties": { "sequence": { "type": "integer" }, "resourceType": { "type": "string", "enum": [ "note", "collection", "transcript", "asset" ] }, "resourceID": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "version": { "type": "integer" }, "changedAt": { "type": "string", "format": "date-time" }, "resource": { "type": "object" } } }, "ChangeListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "changes", "snapshotSequence", "hasMore", "nextCursor" ], "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "snapshotSequence": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } } } ] }, "TranscriptTurnInput": { "type": "object", "required": [ "index", "text" ], "additionalProperties": false, "description": "Request-only transcript turn. Accepts index, speaker, text, startMs, and endMs. noteID and createdAt are response-only.", "properties": { "index": { "type": "integer", "minimum": 0 }, "speaker": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "startMs": { "type": [ "number", "null" ] }, "endMs": { "type": [ "number", "null" ] } } }, "TranscriptTurn": { "type": "object", "required": [ "index", "text" ], "description": "Transcript turn as returned by GET. Includes response-only noteID and createdAt.", "properties": { "noteID": { "type": "string", "format": "uuid" }, "index": { "type": "integer", "minimum": 0 }, "speaker": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "startMs": { "type": [ "number", "null" ] }, "endMs": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "TranscriptAppend": { "type": "object", "required": [ "turns" ], "properties": { "turns": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/TranscriptTurnInput" } } } }, "TranscriptReadResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "turns", "total" ], "properties": { "turns": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptTurn" } }, "nextOffset": { "type": "integer" }, "total": { "type": "integer" } } } ] }, "TranscriptAppendResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "appended", "total" ], "properties": { "appended": { "type": "integer" }, "total": { "type": "integer" } } } ] }, "Asset": { "type": "object", "required": [ "id", "noteID", "fileName", "mimeType", "byteCount", "sha256", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "noteID": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "purpose": { "type": "string" }, "byteCount": { "type": "integer" }, "sha256": { "type": "string" }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "AssetResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "asset" ], "properties": { "asset": { "$ref": "#/components/schemas/Asset" } } } ] }, "AssetCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "note", "asset" ], "properties": { "note": { "$ref": "#/components/schemas/Note" }, "asset": { "$ref": "#/components/schemas/Asset" } } } ] }, "ApiKey": { "type": "object", "required": [ "id", "prefix", "last4", "scopes", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKeyIssue": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "notes:read", "notes:write", "notes:delete", "meetings:read", "assets:read", "assets:write" ] } } } }, "ApiKeyIssueResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "id", "prefix", "last4", "scopes", "createdAt" ], "properties": { "key": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string" }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "keyRedacted": { "type": "boolean" } } } ] }, "ApiKeyListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } ] }, "ApiKeyRevokeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "id", "revokedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revokedAt": { "type": "string", "format": "date-time" } } } ] } }, "responses": { "Unauthorized": { "description": "Missing, invalid, or unverified credentials.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource_metadata for the exact /api/v5 resource when OAuth is enabled." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Paid Harken Pro entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid request body, query, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "ID conflict or idempotency key reuse with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "VersionConflict": { "description": "If-Match did not match the current version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PreconditionRequired": { "description": "If-Match is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Retry later.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "SessionRequired": { "description": "This operation requires a signed-in native Harken session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }