{ "components" : { "schemas" : { "AboutResponse" : { "description" : "What this server is built from.", "properties" : { "components" : { "description" : "The server first, then the libraries it is built on", "items" : { "$ref" : "#/components/schemas/ComponentVersion" }, "type" : "array" } }, "required" : [ "components" ], "type" : "object" }, "ActionCommandConfig" : { "properties" : { "actionName" : { "type" : "string" }, "command" : { "type" : "string" }, "description" : { "type" : "string" } }, "required" : [ "actionName", "command", "description" ], "type" : "object" }, "ActionListItem" : { "properties" : { "canRerun" : { "type" : "boolean" }, "deletable" : { "type" : "boolean" }, "description" : { "type" : "string" }, "inputTypes" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "name" : { "type" : "string" }, "outputTypes" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "readOnly" : { "type" : "boolean" } }, "required" : [ "canRerun", "deletable", "description", "inputTypes", "name", "outputTypes", "readOnly" ], "type" : "object" }, "ActivityJobStats" : { "properties" : { "failures" : { "format" : "int32", "type" : "integer" }, "kind" : { "enum" : [ "BACKGROUND", "HANDLER", "SCHEDULED", "POLL" ], "type" : "string" }, "label" : { "type" : "string" }, "lastEndedAt" : { "type" : "string" }, "maxMs" : { "format" : "int64", "type" : "integer" }, "mine" : { "type" : "boolean" }, "p50Ms" : { "format" : "int64", "type" : "integer" }, "p95Ms" : { "format" : "int64", "type" : "integer" }, "runs" : { "format" : "int32", "type" : "integer" } }, "required" : [ "failures", "kind", "label", "lastEndedAt", "maxMs", "mine", "p50Ms", "p95Ms", "runs" ], "type" : "object" }, "ActivityRow" : { "properties" : { "detail" : { "type" : "string" }, "endedAt" : { "type" : "string" }, "failures" : { "format" : "int32", "type" : "integer" }, "id" : { "type" : "string" }, "kind" : { "enum" : [ "BACKGROUND", "HANDLER", "SCHEDULED", "POLL" ], "type" : "string" }, "label" : { "type" : "string" }, "mine" : { "type" : "boolean" }, "pinned" : { "type" : "boolean" }, "startedAt" : { "type" : "string" }, "state" : { "enum" : [ "RUNNING", "SUCCEEDED", "FAILED" ], "type" : "string" }, "type" : { "type" : "string" } }, "required" : [ "id", "kind", "label", "mine", "pinned", "startedAt", "state" ], "type" : "object" }, "ActivityStats" : { "properties" : { "jobs" : { "items" : { "$ref" : "#/components/schemas/ActivityJobStats" }, "type" : "array" }, "runsPerJob" : { "format" : "int32", "type" : "integer" }, "since" : { "type" : "string" } }, "required" : [ "jobs", "runsPerJob" ], "type" : "object" }, "AddApiRequest" : { "description" : "An API to save to the world", "properties" : { "auth" : { "description" : "Auth scheme the API expects, e.g. bearer", "type" : "string" }, "token_env" : { "description" : "Name of the environment variable holding the token", "type" : "string" }, "type" : { "default" : "openapi", "description" : "openapi (the default) or graphql", "type" : "string" }, "url" : { "description" : "The spec URL — an OpenAPI document or a GraphQL endpoint", "type" : "string" } }, "required" : [ "url" ], "type" : "object" }, "AddRealmRequest" : { "properties" : { "confirmed" : { "type" : "boolean" }, "path" : { "type" : "string" }, "ref" : { "type" : "string" }, "repo" : { "type" : "string" } }, "required" : [ "confirmed" ], "type" : "object" }, "AgentListItem" : { "properties" : { "actions" : { "items" : { "$ref" : "#/components/schemas/ActionListItem" }, "type" : "array" }, "description" : { "type" : "string" }, "goals" : { "items" : { "$ref" : "#/components/schemas/GoalListItem" }, "type" : "array" }, "name" : { "type" : "string" }, "provider" : { "type" : "string" } }, "required" : [ "actions", "description", "goals", "name" ], "type" : "object" }, "AgentProposal" : { "properties" : { "agent" : { "type" : "string" }, "changes" : { "items" : { "$ref" : "#/components/schemas/Change" }, "type" : "array" }, "createdAt" : { "format" : "date-time", "type" : "string" }, "decidedAt" : { "format" : "date-time", "type" : "string" }, "fromVersion" : { "format" : "int32", "type" : "integer" }, "id" : { "type" : "string" }, "ownerId" : { "type" : "string" }, "proven" : { "type" : "boolean" }, "record" : { "type" : "string" }, "refused" : { "type" : "string" }, "status" : { "enum" : [ "OPEN", "ADOPTED", "DISMISSED" ], "type" : "string" }, "summary" : { "type" : "string" } }, "required" : [ "agent", "changes", "createdAt", "id", "ownerId", "proven", "record", "status", "summary" ], "type" : "object" }, "AgentRequest" : { "properties" : { "about" : { "type" : "string" }, "agent" : { "type" : "string" }, "args" : { "type" : "string" }, "decidedAt" : { "format" : "date-time", "type" : "string" }, "decidedBy" : { "type" : "string" }, "detail" : { "type" : "string" }, "evidence" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" }, "expiresAt" : { "format" : "date-time", "type" : "string" }, "id" : { "type" : "string" }, "ownerId" : { "type" : "string" }, "quote" : { "type" : "string" }, "raisedAt" : { "format" : "date-time", "type" : "string" }, "reason" : { "type" : "string" }, "result" : { "type" : "string" }, "routine" : { "type" : "string" }, "runId" : { "type" : "string" }, "status" : { "enum" : [ "PENDING", "APPROVED", "FAILED", "REJECTED", "EXPIRED" ], "type" : "string" }, "untrusted" : { "items" : { "type" : "string" }, "type" : "array" }, "verb" : { "type" : "string" } }, "required" : [ "args", "detail", "evidence", "expiresAt", "id", "ownerId", "raisedAt", "routine", "status", "untrusted", "verb" ], "type" : "object" }, "AgentRun" : { "properties" : { "agent" : { "type" : "string" }, "agentDigest" : { "type" : "string" }, "agentVersion" : { "format" : "int32", "type" : "integer" }, "chain" : { "items" : { "type" : "string" }, "type" : "array" }, "endedAt" : { "format" : "date-time", "type" : "string" }, "error" : { "type" : "string" }, "id" : { "type" : "string" }, "kind" : { "enum" : [ "ROUTINE", "REPAIR", "DUTY_CHECK", "CONVERSATION", "TEST" ], "type" : "string" }, "observing" : { "type" : "boolean" }, "outcome" : { "enum" : [ "RUNNING", "DONE", "FAILED", "TIMED_OUT", "SKIPPED" ], "type" : "string" }, "output" : { "type" : "string" }, "ownerId" : { "type" : "string" }, "principal" : { "type" : "string" }, "repairs" : { "format" : "int32", "type" : "integer" }, "requests" : { "items" : { "type" : "string" }, "type" : "array" }, "runAs" : { "type" : "string" }, "spendByModel" : { "additionalProperties" : { "format" : "double", "type" : "number" }, "type" : "object" }, "spendCents" : { "format" : "double", "type" : "number" }, "startedAt" : { "format" : "date-time", "type" : "string" }, "trigger" : { "type" : "string" }, "violations" : { "format" : "int32", "type" : "integer" }, "work" : { "type" : "string" } }, "required" : [ "chain", "id", "kind", "observing", "outcome", "output", "ownerId", "requests", "runAs", "spendByModel", "spendCents", "startedAt", "trigger", "work" ], "type" : "object" }, "AgentSpec" : { "properties" : { "authority" : { "$ref" : "#/components/schemas/AuthoritySpec" }, "budget" : { "$ref" : "#/components/schemas/BudgetSpec" }, "colleagues" : { "$ref" : "#/components/schemas/ColleaguesSpec" }, "conversation" : { "$ref" : "#/components/schemas/ConversationSpec" }, "disclosesAsAgent" : { "type" : "boolean" }, "duties" : { "items" : { "$ref" : "#/components/schemas/DutySpec" }, "type" : "array" }, "identity" : { "additionalProperties" : { "enum" : [ "own-account", "on-behalf-of" ], "type" : "string" }, "type" : "object" }, "job" : { "type" : "string" }, "models" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "name" : { "type" : "string" }, "operators" : { "items" : { "type" : "string" }, "type" : "array" }, "owners" : { "items" : { "type" : "string" }, "type" : "array" }, "persona" : { "type" : "string" }, "qos" : { "$ref" : "#/components/schemas/QosSpec" }, "realm" : { "type" : "string" }, "routines" : { "items" : { "$ref" : "#/components/schemas/RoutineRef" }, "type" : "array" }, "routing" : { "type" : "string" }, "sponsor" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" }, "state" : { "enum" : [ "draft", "submitted", "active", "suspended", "retired" ], "type" : "string" }, "version" : { "format" : "int32", "type" : "integer" } }, "required" : [ "disclosesAsAgent", "duties", "identity", "job", "models", "name", "operators", "owners", "routines", "routing", "stage", "state", "version" ], "type" : "object" }, "AgentSuggestion" : { "properties" : { "adopt" : { "type" : "string" }, "agent" : { "$ref" : "#/components/schemas/AgentSpec" }, "createdAt" : { "format" : "date-time", "type" : "string" }, "decidedAt" : { "format" : "date-time", "type" : "string" }, "evidence" : { "items" : { "$ref" : "#/components/schemas/Evidence" }, "type" : "array" }, "feasibility" : { "type" : "string" }, "id" : { "type" : "string" }, "job" : { "type" : "string" }, "kind" : { "enum" : [ "WORKS", "TALKS" ], "type" : "string" }, "name" : { "type" : "string" }, "ownerId" : { "type" : "string" }, "preview" : { "items" : { "type" : "string" }, "type" : "array" }, "rank" : { "format" : "int32", "type" : "integer" }, "status" : { "enum" : [ "OPEN", "DRAFTED", "ADOPTED", "DISMISSED" ], "type" : "string" }, "uncovered" : { "type" : "string" } }, "required" : [ "createdAt", "evidence", "feasibility", "id", "job", "kind", "name", "ownerId", "preview", "rank", "status" ], "type" : "object" }, "AgentVersionView" : { "properties" : { "digest" : { "type" : "string" }, "routines" : { "items" : { "type" : "string" }, "type" : "array" }, "signedAt" : { "type" : "string" }, "signedBy" : { "type" : "string" }, "version" : { "format" : "int32", "type" : "integer" } }, "required" : [ "digest", "routines", "signedAt", "signedBy", "version" ], "type" : "object" }, "AgentView" : { "properties" : { "authority" : { "$ref" : "#/components/schemas/AuthoritySpec" }, "budget" : { "$ref" : "#/components/schemas/BudgetSpec" }, "duties" : { "items" : { "$ref" : "#/components/schemas/DutyView" }, "type" : "array" }, "identity" : { "additionalProperties" : { "enum" : [ "own-account", "on-behalf-of" ], "type" : "string" }, "type" : "object" }, "job" : { "type" : "string" }, "name" : { "type" : "string" }, "needs" : { "items" : { "type" : "string" }, "type" : "array" }, "operators" : { "items" : { "type" : "string" }, "type" : "array" }, "origin" : { "type" : "string" }, "owners" : { "items" : { "type" : "string" }, "type" : "array" }, "persona" : { "type" : "string" }, "qos" : { "$ref" : "#/components/schemas/QosSpec" }, "routines" : { "items" : { "$ref" : "#/components/schemas/RoutineView" }, "type" : "array" }, "routing" : { "type" : "string" }, "signedAt" : { "type" : "string" }, "signedBy" : { "type" : "string" }, "sponsor" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" }, "state" : { "enum" : [ "draft", "submitted", "active", "suspended", "retired" ], "type" : "string" }, "unsignedChanges" : { "items" : { "type" : "string" }, "type" : "array" }, "version" : { "format" : "int32", "type" : "integer" } }, "required" : [ "duties", "identity", "job", "name", "needs", "operators", "origin", "owners", "routines", "routing", "stage", "state", "unsignedChanges", "version" ], "type" : "object" }, "AnnotateDryRunRequest" : { "properties" : { "params" : { "additionalProperties" : { }, "type" : "object" }, "statement" : { "type" : "string" } }, "required" : [ "params", "statement" ], "type" : "object" }, "AnswerRequest" : { "properties" : { "choice" : { "type" : "string" }, "subject" : { "type" : "string" } }, "required" : [ "choice", "subject" ], "type" : "object" }, "ApiModesResponse" : { "properties" : { "modes" : { "items" : { "$ref" : "#/components/schemas/EngineWire" }, "type" : "array" } }, "required" : [ "modes" ], "type" : "object" }, "ArtifactWriteRequest" : { "description" : "An artifact's new content", "properties" : { "content" : { "description" : "The content to store, verbatim", "type" : "string" } }, "required" : [ "content" ], "type" : "object" }, "AskRequest" : { "properties" : { "answer" : { "type" : "boolean" }, "history" : { "items" : { "type" : "string" }, "type" : "array" }, "intent" : { "type" : "string" }, "maxSnippet" : { "format" : "int32", "type" : "integer" }, "minScore" : { "format" : "double", "type" : "number" }, "question" : { "type" : "string" }, "tag" : { "description" : "Narrow to documents carrying this tag, whether or not an answer is composed.", "type" : "string" }, "topK" : { "format" : "int32", "type" : "integer" }, "uri" : { "description" : "Narrow to the one document at this uri, as GET /documents lists it, whether or not an answer is composed. A uri the caller's world does not hold is answered 404.", "type" : "string" }, "window" : { "$ref" : "#/components/schemas/DateWindow" } }, "required" : [ "answer", "history", "question" ], "type" : "object" }, "AskResponse" : { "properties" : { "answer" : { "type" : "string" }, "filters" : { "additionalProperties" : { }, "type" : "object" }, "model" : { "type" : "string" }, "note" : { "type" : "string" }, "raw" : { "type" : "string" }, "sources" : { "items" : { "$ref" : "#/components/schemas/Source" }, "type" : "array" }, "unresolvedCitations" : { "format" : "int32", "type" : "integer" } }, "required" : [ "filters", "sources", "unresolvedCitations" ], "type" : "object" }, "Attachment" : { "properties" : { "args" : { "additionalProperties" : { }, "type" : "object" }, "capturedAt" : { "format" : "date-time", "type" : "string" }, "id" : { "type" : "string" }, "kind" : { "enum" : [ "ENTITY", "VIEW", "REQUEST" ], "type" : "string" }, "label" : { "type" : "string" }, "properties" : { "additionalProperties" : { }, "type" : "object" }, "rows" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" }, "title" : { "type" : "string" } }, "required" : [ "args", "kind", "label", "properties", "rows", "title" ], "type" : "object" }, "AttachmentActivity" : { "properties" : { "filename" : { "type" : "string" }, "finishedAt" : { "type" : "string" }, "handler" : { "type" : "string" }, "stale" : { "type" : "boolean" }, "startedAt" : { "type" : "string" }, "state" : { "enum" : [ "IMPORTING", "IMPORTED", "FAILED" ], "type" : "string" }, "summary" : { "type" : "string" } }, "required" : [ "filename", "handler", "stale", "startedAt", "state", "summary" ], "type" : "object" }, "AttachmentRequest" : { "properties" : { "args" : { "additionalProperties" : { }, "type" : "object" }, "id" : { "type" : "string" }, "kind" : { "enum" : [ "ENTITY", "VIEW", "REQUEST" ], "type" : "string" }, "label" : { "type" : "string" }, "properties" : { "additionalProperties" : { }, "type" : "object" }, "title" : { "type" : "string" } }, "required" : [ "args", "kind", "label", "properties", "title" ], "type" : "object" }, "AuthoritySpec" : { "properties" : { "default" : { "enum" : [ "act", "request", "never" ], "type" : "string" }, "observe" : { "items" : { "enum" : [ "authority", "sensitive", "egress", "review" ], "type" : "string" }, "type" : "array", "uniqueItems" : true }, "reach" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "review" : { "type" : "boolean" }, "verbs" : { "additionalProperties" : { "enum" : [ "act", "request", "never" ], "type" : "string" }, "type" : "object" } }, "required" : [ "default", "observe", "review", "verbs" ], "type" : "object" }, "AvailableSourcesResponse" : { "properties" : { "sources" : { "items" : { "$ref" : "#/components/schemas/OnboardingSource" }, "type" : "array" } }, "required" : [ "sources" ], "type" : "object" }, "BootstrapCapabilities" : { "properties" : { "apiDiscoveryEnabled" : { "type" : "boolean" }, "workosEnabled" : { "type" : "boolean" } }, "required" : [ "apiDiscoveryEnabled", "workosEnabled" ], "type" : "object" }, "BootstrapResponse" : { "properties" : { "capabilities" : { "$ref" : "#/components/schemas/BootstrapCapabilities" }, "currentUser" : { "$ref" : "#/components/schemas/BootstrapUser" }, "preferredLogin" : { "type" : "string" }, "schemaVersion" : { "format" : "int32", "type" : "integer" }, "supportedAuthSchemes" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "capabilities", "preferredLogin", "schemaVersion", "supportedAuthSchemes" ], "type" : "object" }, "BootstrapUser" : { "properties" : { "displayName" : { "type" : "string" }, "username" : { "type" : "string" } }, "required" : [ "username" ], "type" : "object" }, "BriefingLensRequest" : { "properties" : { "asOf" : { "type" : "string" }, "lookbackDays" : { "format" : "int32", "type" : "integer" }, "since" : { "type" : "string" } }, "type" : "object" }, "BrowserLocationRequest" : { "properties" : { "lat" : { "format" : "double", "type" : "number" }, "lng" : { "format" : "double", "type" : "number" } }, "required" : [ "lat", "lng" ], "type" : "object" }, "BrowserTimeZoneRequest" : { "properties" : { "zone" : { "type" : "string" } }, "required" : [ "zone" ], "type" : "object" }, "BudgetSpec" : { "properties" : { "concurrentRuns" : { "format" : "int32", "type" : "integer" }, "expiresOn" : { "type" : "string" }, "requestsPerRun" : { "format" : "int32", "type" : "integer" }, "runsPerHour" : { "format" : "int32", "type" : "integer" }, "sourceShares" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "type" : "object" }, "spendPerDayCents" : { "format" : "int32", "type" : "integer" }, "spendPerRunCents" : { "format" : "int32", "type" : "integer" }, "writesPerDay" : { "format" : "int32", "type" : "integer" } }, "required" : [ "sourceShares" ], "type" : "object" }, "BuildSnapshot" : { "properties" : { "byOutcome" : { "items" : { "$ref" : "#/components/schemas/TimerSummary" }, "type" : "array" }, "recorded" : { "type" : "boolean" }, "wasmBytes" : { "$ref" : "#/components/schemas/DistributionSnapshot" } }, "required" : [ "byOutcome", "recorded" ], "type" : "object" }, "CalendarAccount" : { "properties" : { "accountId" : { "type" : "string" }, "displayName" : { "type" : "string" }, "provider" : { "type" : "string" } }, "required" : [ "accountId", "displayName", "provider" ], "type" : "object" }, "CalendarConnectionsView" : { "properties" : { "accounts" : { "items" : { "$ref" : "#/components/schemas/ConnectedAccountView" }, "type" : "array" }, "providers" : { "items" : { "$ref" : "#/components/schemas/ConnectionProviderView" }, "type" : "array" } }, "required" : [ "accounts", "providers" ], "type" : "object" }, "CalendarEvent" : { "properties" : { "account" : { "$ref" : "#/components/schemas/CalendarAccount" }, "attendees" : { "items" : { "$ref" : "#/components/schemas/EventAttendee" }, "type" : "array" }, "calendarId" : { "type" : "string" }, "description" : { "type" : "string" }, "end" : { "format" : "date-time", "type" : "string" }, "eventId" : { "type" : "string" }, "isAllDay" : { "type" : "boolean" }, "isRecurring" : { "type" : "boolean" }, "joinUrl" : { "type" : "string" }, "location" : { "type" : "string" }, "myResponse" : { "enum" : [ "NEEDS_ACTION", "ACCEPTED", "TENTATIVE", "DECLINED" ], "type" : "string" }, "organizer" : { "$ref" : "#/components/schemas/EventAttendee" }, "start" : { "format" : "date-time", "type" : "string" }, "timeZone" : { "type" : "string" }, "title" : { "type" : "string" }, "url" : { "type" : "string" }, "visibility" : { "enum" : [ "DEFAULT", "PUBLIC", "PRIVATE", "CONFIDENTIAL" ], "type" : "string" } }, "required" : [ "attendees", "calendarId", "description", "end", "eventId", "isAllDay", "isRecurring", "myResponse", "start", "timeZone", "title", "visibility" ], "type" : "object" }, "CapabilitiesRequest" : { "properties" : { "verbs" : { "items" : { "$ref" : "#/components/schemas/VerbSpec" }, "type" : "array" } }, "required" : [ "verbs" ], "type" : "object" }, "Change" : { "properties" : { "duty" : { "$ref" : "#/components/schemas/NewDuty" }, "evidence" : { "type" : "string" }, "from" : { "type" : "string" }, "target" : { "type" : "string" }, "to" : { "type" : "string" }, "why" : { "type" : "string" } }, "required" : [ "evidence", "target", "to", "why" ], "type" : "object" }, "ChangeRequest" : { "properties" : { "model" : { "type" : "string" } }, "required" : [ "model" ], "type" : "object" }, "ChannelsResponse" : { "properties" : { "joined" : { "items" : { "type" : "string" }, "type" : "array" }, "offered" : { "items" : { "$ref" : "#/components/schemas/OfferedChannel" }, "type" : "array" } }, "required" : [ "joined", "offered" ], "type" : "object" }, "ChatCompletion" : { "properties" : { "choices" : { "items" : { "$ref" : "#/components/schemas/Choice" }, "type" : "array" }, "created" : { "format" : "int64", "type" : "integer" }, "embabel" : { "$ref" : "#/components/schemas/Evidence" }, "id" : { "type" : "string" }, "model" : { "type" : "string" }, "object" : { "type" : "string" } }, "required" : [ "choices", "created", "id", "model", "object" ], "type" : "object" }, "ChatCompletionRequest" : { "properties" : { "embabel_conversation" : { "type" : "string" }, "embabel_evidence" : { "type" : "boolean" }, "embabel_observing" : { "type" : "boolean" }, "embabel_realms" : { "items" : { "type" : "string" }, "type" : "array" }, "embabel_verbosity" : { "type" : "string" }, "max_completion_tokens" : { "format" : "int32", "type" : "integer" }, "max_tokens" : { "format" : "int32", "type" : "integer" }, "messages" : { "items" : { "$ref" : "#/components/schemas/RequestMessage" }, "type" : "array" }, "model" : { "type" : "string" }, "stream" : { "type" : "boolean" }, "temperature" : { "format" : "double", "type" : "number" }, "user" : { "type" : "string" } }, "required" : [ "messages" ], "type" : "object" }, "ChatFeedbackRequest" : { "properties" : { "text" : { "type" : "string" }, "verdict" : { "type" : "string" } }, "required" : [ "text", "verdict" ], "type" : "object" }, "ChatRequest" : { "properties" : { "message" : { "type" : "string" } }, "required" : [ "message" ], "type" : "object" }, "Choice" : { "properties" : { "finish_reason" : { "type" : "string" }, "index" : { "format" : "int32", "type" : "integer" }, "message" : { "$ref" : "#/components/schemas/Message" } }, "required" : [ "finish_reason", "index", "message" ], "type" : "object" }, "ColleaguesSpec" : { "properties" : { "mayBeMessagedBy" : { "items" : { "type" : "string" }, "type" : "array" }, "mayMessage" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "mayBeMessagedBy", "mayMessage" ], "type" : "object" }, "CollectorConfig" : { "properties" : { "cron" : { "type" : "string" }, "dryRun" : { "type" : "boolean" }, "enabled" : { "type" : "boolean" }, "entityOverlap" : { "format" : "double", "type" : "number" }, "groundingOverlap" : { "format" : "double", "type" : "number" }, "lexical" : { "format" : "double", "type" : "number" }, "matcher" : { "type" : "string" }, "provenanceOverlap" : { "format" : "double", "type" : "number" }, "similarityThreshold" : { "format" : "double", "type" : "number" }, "vector" : { "format" : "double", "type" : "number" } }, "type" : "object" }, "CollectorSettingsRequest" : { "properties" : { "cron" : { "type" : "string" }, "dryRun" : { "type" : "boolean" }, "enabled" : { "type" : "boolean" }, "matcher" : { "type" : "string" }, "similarityThreshold" : { "format" : "double", "type" : "number" } }, "required" : [ "cron", "dryRun", "enabled", "matcher", "similarityThreshold" ], "type" : "object" }, "CommandRunRequest" : { "properties" : { "argument" : { "type" : "string" } }, "type" : "object" }, "CompileAndScheduleRequest" : { "properties" : { "cron" : { "type" : "string" }, "description" : { "type" : "string" }, "inputTypeNames" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "name" : { "type" : "string" }, "outputTypeName" : { "type" : "string" }, "toolNames" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "cron", "description", "name" ], "type" : "object" }, "CompileRequest" : { "properties" : { "description" : { "type" : "string" }, "inputTypeNames" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "llmModel" : { "type" : "string" }, "llmTemperature" : { "format" : "double", "type" : "number" }, "name" : { "type" : "string" }, "outputTypeName" : { "type" : "string" }, "referenceNames" : { "items" : { "type" : "string" }, "type" : "array" }, "toolNames" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "description", "name" ], "type" : "object" }, "CompileScheduleRequest" : { "description" : "A schedule described in natural language", "properties" : { "schedule" : { "description" : "The schedule in words, e.g. 'every day at 7am'", "type" : "string" } }, "required" : [ "schedule" ], "type" : "object" }, "ComponentVersion" : { "description" : "One part of the running server and the build of it that is running.", "properties" : { "commit" : { "description" : "Full git commit SHA, when the component was built with one", "type" : "string" }, "name" : { "description" : "Human name of the component", "example" : "Embabel Agent", "type" : "string" }, "version" : { "description" : "Released or snapshot version, when the component carries one", "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "ConnectApiRequest" : { "properties" : { "fields" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "headerName" : { "type" : "string" }, "mode" : { "type" : "string" }, "name" : { "type" : "string" }, "specUrl" : { "type" : "string" }, "token" : { "type" : "string" } }, "required" : [ "fields" ], "type" : "object" }, "ConnectDatabaseRequest" : { "properties" : { "engine" : { "type" : "string" }, "fields" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "jdbcUrl" : { "type" : "string" }, "password" : { "type" : "string" }, "username" : { "type" : "string" } }, "required" : [ "fields", "password", "username" ], "type" : "object" }, "ConnectedAccountView" : { "properties" : { "accountId" : { "type" : "string" }, "displayName" : { "type" : "string" }, "provider" : { "type" : "string" } }, "required" : [ "accountId", "displayName", "provider" ], "type" : "object" }, "ConnectionProviderView" : { "properties" : { "authorizeUrl" : { "type" : "string" }, "configured" : { "type" : "boolean" }, "displayName" : { "type" : "string" }, "providerName" : { "type" : "string" } }, "required" : [ "authorizeUrl", "configured", "displayName", "providerName" ], "type" : "object" }, "Context" : { "allOf" : [ { "$ref" : "#/components/schemas/SensorEvent" }, { "properties" : { "activities" : { "items" : { "type" : "string" }, "type" : "array" }, "app" : { "type" : "string" }, "confidence" : { "format" : "double", "type" : "number" }, "detail" : { "type" : "string" }, "focusMode" : { "type" : "string" }, "locked" : { "type" : "boolean" }, "media" : { "type" : "string" }, "stream" : { "type" : "string" } }, "type" : "object" } ], "required" : [ "activities", "stream" ] }, "ContextRequest" : { "properties" : { "model" : { "description" : "The model the context is pinned to", "type" : "string" }, "role" : { "description" : "The role the context uses", "type" : "string" } }, "type" : "object" }, "ContextView" : { "properties" : { "deploymentModel" : { "type" : "string" }, "deploymentRole" : { "type" : "string" }, "followsChat" : { "type" : "boolean" }, "id" : { "type" : "string" }, "model" : { "type" : "string" }, "resolved" : { "$ref" : "#/components/schemas/ResolvedModel" }, "role" : { "type" : "string" }, "roleInUse" : { "type" : "string" } }, "required" : [ "followsChat", "id" ], "type" : "object" }, "ConversationSpec" : { "properties" : { "builtins" : { }, "llm" : { "type" : "string" }, "realms" : { "items" : { "type" : "string" }, "type" : "array" }, "sampling" : { "$ref" : "#/components/schemas/SamplingSpec" } }, "required" : [ "realms" ], "type" : "object" }, "ConversionFailure" : { "properties" : { "at" : { "format" : "date-time", "type" : "string" }, "converter" : { "type" : "string" }, "document" : { "type" : "string" }, "reason" : { "type" : "string" } }, "required" : [ "at", "converter", "document", "reason" ], "type" : "object" }, "ConversionStatus" : { "description" : "Which converter turns documents into structured text, and how it is doing", "properties" : { "converter" : { "description" : "The active converter's name; 'none' when documents go straight to flat text extraction", "type" : "string" }, "docling" : { "$ref" : "#/components/schemas/DoclingStatus" }, "failuresSinceStart" : { "description" : "Conversions that failed and fell back to flat text since the app started", "format" : "int64", "type" : "integer" }, "recentFailures" : { "description" : "The most recent of those, newest last", "items" : { "$ref" : "#/components/schemas/ConversionFailure" }, "type" : "array" } }, "required" : [ "converter", "docling", "failuresSinceStart", "recentFailures" ], "type" : "object" }, "Counts" : { "properties" : { "requestsToday" : { "format" : "int32", "type" : "integer" }, "runsLastHour" : { "format" : "int32", "type" : "integer" }, "writesToday" : { "format" : "int32", "type" : "integer" } }, "required" : [ "requestsToday", "runsLastHour", "writesToday" ], "type" : "object" }, "CpuStatus" : { "description" : "CPU load, as fractions of what this JVM may use", "properties" : { "processLoad" : { "description" : "This app's share of the CPU it may use, 0.0–1.0. Null when not yet measured.", "format" : "double", "type" : "number" }, "processors" : { "description" : "Processors available to the JVM", "format" : "int32", "type" : "integer" }, "systemLoad" : { "description" : "The whole machine's load, 0.0–1.0 — in a container, the container's quota. Null when not yet measured.", "format" : "double", "type" : "number" } }, "required" : [ "processors" ], "type" : "object" }, "CreateLensRequest" : { "properties" : { "name" : { "type" : "string" }, "params" : { "items" : { "$ref" : "#/components/schemas/LensParam" }, "type" : "array" }, "persona" : { "type" : "string" }, "schedule" : { "type" : "string" }, "script" : { "type" : "string" } }, "required" : [ "name", "params", "script" ], "type" : "object" }, "CreatePersonalityRequest" : { "properties" : { "from" : { "type" : "string" }, "name" : { "type" : "string" }, "slug" : { "type" : "string" } }, "required" : [ "name", "slug" ], "type" : "object" }, "CreateSkillRequest" : { "properties" : { "description" : { "type" : "string" }, "instructions" : { "type" : "string" }, "name" : { "type" : "string" } }, "required" : [ "description", "instructions", "name" ], "type" : "object" }, "CreateThreadRequest" : { "properties" : { "title" : { "type" : "string" } }, "required" : [ "title" ], "type" : "object" }, "CreateWatchRequest" : { "properties" : { "cron" : { "type" : "string" }, "delivery" : { "$ref" : "#/components/schemas/DeliverySpec" }, "diffSpec" : { "$ref" : "#/components/schemas/DiffSpec" }, "enabled" : { "type" : "boolean" }, "firstRunPolicy" : { "enum" : [ "ESTABLISH_BASELINE", "EMIT_CURRENT" ], "type" : "string" }, "lensId" : { "type" : "string" }, "name" : { "type" : "string" }, "params" : { "additionalProperties" : { }, "type" : "object" } }, "required" : [ "diffSpec", "enabled", "firstRunPolicy", "lensId", "name", "params" ], "type" : "object" }, "CreateWorldRequest" : { "description" : "A new world's name", "properties" : { "name" : { "description" : "The world's name; no slashes and no '..'", "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "CronJobConfig" : { "properties" : { "actionName" : { "type" : "string" }, "cron" : { "type" : "string" }, "description" : { "type" : "string" }, "name" : { "type" : "string" }, "payload" : { "additionalProperties" : { }, "type" : "object" }, "zone" : { "type" : "string" } }, "required" : [ "actionName", "cron", "description", "name", "payload" ], "type" : "object" }, "DataContractBindingSpec" : { "properties" : { "id" : { "type" : "string" }, "mode" : { "enum" : [ "observe", "enforce" ], "type" : "string" }, "object" : { "type" : "string" }, "version" : { "type" : "string" } }, "required" : [ "id", "mode", "object", "version" ], "type" : "object" }, "DataContractCheck" : { "properties" : { "kind" : { "type" : "string" }, "message" : { "type" : "string" }, "ruleId" : { "type" : "string" }, "scope" : { "type" : "string" }, "verdict" : { "enum" : [ "PASS", "WARN", "FAIL", "UNKNOWN" ], "type" : "string" } }, "required" : [ "kind", "ruleId", "verdict" ], "type" : "object" }, "DataContractEvaluation" : { "properties" : { "apiVersion" : { "type" : "string" }, "available" : { "type" : "boolean" }, "blocksRows" : { "type" : "boolean" }, "checkedAt" : { "type" : "string" }, "checks" : { "items" : { "$ref" : "#/components/schemas/DataContractCheck" }, "type" : "array" }, "id" : { "type" : "string" }, "mode" : { "enum" : [ "observe", "enforce" ], "type" : "string" }, "object" : { "type" : "string" }, "status" : { "type" : "string" }, "verdict" : { "enum" : [ "PASS", "WARN", "FAIL", "UNKNOWN" ], "type" : "string" }, "version" : { "type" : "string" } }, "required" : [ "apiVersion", "available", "blocksRows", "checkedAt", "checks", "id", "mode", "object", "status", "verdict", "version" ], "type" : "object" }, "DateWindow" : { "properties" : { "field" : { "type" : "string" }, "from" : { "type" : "string" }, "to" : { "type" : "string" } }, "type" : "object" }, "DecisionRequest" : { "properties" : { "decision" : { "type" : "string" }, "reason" : { "type" : "string" } }, "required" : [ "decision" ], "type" : "object" }, "DecisionResponse" : { "properties" : { "refused" : { "type" : "string" }, "request" : { "$ref" : "#/components/schemas/AgentRequest" } }, "type" : "object" }, "DeliverySpec" : { "properties" : { "channel" : { "type" : "string" }, "format" : { "type" : "string" }, "headers" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "secret" : { "type" : "string" }, "tier" : { "type" : "string" }, "url" : { "type" : "string" } }, "required" : [ "channel", "format", "headers", "tier" ], "type" : "object" }, "DeploymentUse" : { "properties" : { "model" : { "type" : "string" }, "role" : { "type" : "string" }, "setting" : { "type" : "string" } }, "required" : [ "setting" ], "type" : "object" }, "DiffSpec" : { "properties" : { "compareFields" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "ignoreFields" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "keyPath" : { "type" : "string" }, "keyedListFields" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "resultMode" : { "enum" : [ "AUTO", "ENTITIES", "STRUCTURED" ], "type" : "string" }, "setFields" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "transitions" : { "items" : { "$ref" : "#/components/schemas/TransitionRule" }, "type" : "array" } }, "required" : [ "compareFields", "ignoreFields", "keyedListFields", "resultMode", "setFields", "transitions" ], "type" : "object" }, "DirectoryEntry" : { "properties" : { "description" : { "type" : "string" }, "metadata" : { "additionalProperties" : { }, "type" : "object" }, "name" : { "type" : "string" }, "source" : { "type" : "string" }, "type" : { "enum" : [ "SKILL", "API", "MCP_SERVER", "REALM" ], "type" : "string" }, "url" : { "type" : "string" } }, "required" : [ "description", "metadata", "name", "source", "type" ], "type" : "object" }, "DirectoryRefreshResponse" : { "properties" : { "refreshed" : { "type" : "boolean" } }, "required" : [ "refreshed" ], "type" : "object" }, "DiscoverRequest" : { "properties" : { "query" : { "type" : "string" } }, "required" : [ "query" ], "type" : "object" }, "DiscoveredEndpoint" : { "properties" : { "description" : { "type" : "string" }, "method" : { "type" : "string" }, "parameters" : { "items" : { "$ref" : "#/components/schemas/DiscoveredParameter" }, "type" : "array" }, "path" : { "type" : "string" }, "verified" : { "type" : "boolean" } }, "required" : [ "description", "method", "parameters", "path", "verified" ], "type" : "object" }, "DiscoveredParameter" : { "properties" : { "description" : { "type" : "string" }, "location" : { "type" : "string" }, "name" : { "type" : "string" }, "required" : { "type" : "boolean" }, "type" : { "type" : "string" } }, "required" : [ "location", "name", "required", "type" ], "type" : "object" }, "DiscoveryResult" : { "properties" : { "authDetails" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "authType" : { "type" : "string" }, "baseUrl" : { "type" : "string" }, "description" : { "type" : "string" }, "discoveredAt" : { "format" : "date-time", "type" : "string" }, "endpoints" : { "items" : { "$ref" : "#/components/schemas/DiscoveredEndpoint" }, "type" : "array" }, "name" : { "type" : "string" }, "sources" : { "items" : { "type" : "string" }, "type" : "array" }, "specType" : { "type" : "string" }, "specUrl" : { "type" : "string" }, "synthesized" : { "type" : "boolean" } }, "required" : [ "authDetails", "authType", "description", "discoveredAt", "endpoints", "name", "sources", "specType", "specUrl", "synthesized" ], "type" : "object" }, "DismissPinBody" : { "properties" : { "label" : { "type" : "string" } }, "required" : [ "label" ], "type" : "object" }, "DismissRequest" : { "properties" : { "dismissed" : { "type" : "boolean" } }, "required" : [ "dismissed" ], "type" : "object" }, "DispatchSnapshot" : { "properties" : { "byOutcome" : { "items" : { "$ref" : "#/components/schemas/TimerSummary" }, "type" : "array" }, "hostCalls" : { "format" : "double", "type" : "number" }, "memoryBytes" : { "$ref" : "#/components/schemas/DistributionSnapshot" } }, "required" : [ "byOutcome", "hostCalls" ], "type" : "object" }, "DisplayNameBody" : { "properties" : { "name" : { "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "DistributionSnapshot" : { "properties" : { "baseUnit" : { "type" : "string" }, "count" : { "format" : "int64", "type" : "integer" }, "max" : { "format" : "double", "type" : "number" }, "total" : { "format" : "double", "type" : "number" } }, "required" : [ "count", "max", "total" ], "type" : "object" }, "DoclingStatus" : { "description" : "The docling conversion service", "properties" : { "inUse" : { "description" : "Whether docling is the active converter", "type" : "boolean" }, "reachable" : { "description" : "Whether docling answered its health check just now. Null when it is not in use and was not asked.", "type" : "boolean" } }, "required" : [ "inUse" ], "type" : "object" }, "DocumentNotFound" : { "properties" : { "error" : { "type" : "string" } }, "required" : [ "error" ], "type" : "object" }, "DocumentOutlineView" : { "properties" : { "message" : { "type" : "string" }, "sections" : { "items" : { "$ref" : "#/components/schemas/SectionHeadingView" }, "type" : "array" }, "title" : { "type" : "string" }, "uri" : { "type" : "string" } }, "required" : [ "sections", "uri" ], "type" : "object" }, "DocumentSectionView" : { "properties" : { "section" : { "$ref" : "#/components/schemas/SectionHeadingView" }, "text" : { "type" : "string" }, "uri" : { "type" : "string" } }, "required" : [ "section", "uri" ], "type" : "object" }, "DutyCheck" : { "properties" : { "agent" : { "type" : "string" }, "agentVersion" : { "format" : "int32", "type" : "integer" }, "checkedAt" : { "format" : "date-time", "type" : "string" }, "duty" : { "type" : "string" }, "lapsedSince" : { "format" : "date-time", "type" : "string" }, "onDemand" : { "type" : "boolean" }, "onFallbacks" : { "type" : "boolean" }, "reason" : { "type" : "string" }, "repairFailures" : { "format" : "int32", "type" : "integer" }, "repaired" : { "format" : "int32", "type" : "integer" }, "state" : { "enum" : [ "upheld", "lapsed", "neglected", "unknown" ], "type" : "string" }, "violations" : { "format" : "int32", "type" : "integer" }, "wouldHaveCalled" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "agent", "checkedAt", "duty", "onDemand", "onFallbacks", "repairFailures", "repaired", "state", "violations", "wouldHaveCalled" ], "type" : "object" }, "DutySpec" : { "properties" : { "every" : { "type" : "string" }, "holds" : { "type" : "string" }, "name" : { "type" : "string" }, "repair" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" }, "text" : { "type" : "string" }, "timezone" : { "type" : "string" } }, "required" : [ "holds", "name", "text" ], "type" : "object" }, "DutyView" : { "properties" : { "checkedAt" : { "format" : "date-time", "type" : "string" }, "every" : { "type" : "string" }, "holds" : { "type" : "string" }, "lapsedSince" : { "format" : "date-time", "type" : "string" }, "name" : { "type" : "string" }, "reason" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" }, "state" : { "enum" : [ "upheld", "lapsed", "neglected", "unknown" ], "type" : "string" }, "status" : { "type" : "string" }, "testedAt" : { "format" : "date-time", "type" : "string" }, "testedVersion" : { "format" : "int32", "type" : "integer" }, "text" : { "type" : "string" }, "timezone" : { "type" : "string" }, "violations" : { "format" : "int32", "type" : "integer" } }, "required" : [ "holds", "name", "stage", "status", "text", "violations" ], "type" : "object" }, "EdgeRequest" : { "properties" : { "from" : { "type" : "string" }, "to" : { "type" : "string" }, "type" : { "type" : "string" } }, "required" : [ "from", "to", "type" ], "type" : "object" }, "EmailAccount" : { "properties" : { "accountId" : { "type" : "string" }, "displayName" : { "type" : "string" }, "provider" : { "type" : "string" } }, "required" : [ "accountId", "displayName", "provider" ], "type" : "object" }, "EmailAttachment" : { "properties" : { "extractedText" : { "type" : "string" }, "filename" : { "type" : "string" }, "mimeType" : { "type" : "string" }, "sizeBytes" : { "format" : "int32", "type" : "integer" } }, "required" : [ "extractedText", "filename", "mimeType", "sizeBytes" ], "type" : "object" }, "EmailConnectionsView" : { "properties" : { "accounts" : { "items" : { "$ref" : "#/components/schemas/ConnectedAccountView" }, "type" : "array" }, "providers" : { "items" : { "$ref" : "#/components/schemas/ConnectionProviderView" }, "type" : "array" } }, "required" : [ "accounts", "providers" ], "type" : "object" }, "EmailMessage" : { "properties" : { "attachments" : { "items" : { "$ref" : "#/components/schemas/EmailAttachment" }, "type" : "array" }, "autoSubmitted" : { "type" : "boolean" }, "body" : { "type" : "string" }, "cc" : { "items" : { "type" : "string" }, "type" : "array" }, "from" : { "type" : "string" }, "hasAttachments" : { "type" : "boolean" }, "labels" : { "items" : { "type" : "string" }, "type" : "array" }, "messageId" : { "type" : "string" }, "receivedAt" : { "format" : "date-time", "type" : "string" }, "subject" : { "type" : "string" }, "to" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "attachments", "autoSubmitted", "body", "cc", "from", "hasAttachments", "labels", "messageId", "receivedAt", "subject", "to" ], "type" : "object" }, "EmailThread" : { "properties" : { "account" : { "$ref" : "#/components/schemas/EmailAccount" }, "lastMessageAt" : { "format" : "date-time", "type" : "string" }, "messages" : { "items" : { "$ref" : "#/components/schemas/EmailMessage" }, "type" : "array" }, "participants" : { "items" : { "type" : "string" }, "type" : "array" }, "source" : { "$ref" : "#/components/schemas/EmailThreadSource" }, "subject" : { "type" : "string" }, "threadId" : { "type" : "string" } }, "required" : [ "lastMessageAt", "messages", "participants", "source", "subject", "threadId" ], "type" : "object" }, "EmailThreadSource" : { "properties" : { "provider" : { "type" : "string" }, "url" : { "type" : "string" } }, "required" : [ "provider" ], "type" : "object" }, "EmbedMissingRequest" : { "properties" : { "uri" : { "type" : "string" } }, "required" : [ "uri" ], "type" : "object" }, "EmbeddingsStatus" : { "description" : "The embedding model, where it runs, and whether every stored chunk has the embedding vector search needs", "properties" : { "chunksWithoutEmbedding" : { "description" : "Chunks stored with no embedding, which vector search cannot return — left by an embedding request that failed during ingest. A re-embed, which runs only when the embedding model changes, fills them. Null when the graph could not be read; refreshed at most every 30 seconds.", "format" : "int64", "type" : "integer" }, "model" : { "description" : "The embedding model in use. Null when none is configured, so document features are off.", "type" : "string" }, "modelRunner" : { "$ref" : "#/components/schemas/ModelRunnerActivity", "description" : "What Docker Model Runner says about its embedding model now. Null when the model is not served by Docker Model Runner, or it did not answer." }, "provider" : { "description" : "Who serves that model: 'onnx' runs inside the app; 'Docker' is Docker Model Runner on the host", "type" : "string" } }, "type" : "object" }, "EngineFieldWire" : { "properties" : { "default" : { "type" : "string" }, "label" : { "type" : "string" }, "name" : { "type" : "string" }, "placeholder" : { "type" : "string" }, "required" : { "type" : "boolean" }, "secret" : { "type" : "boolean" } }, "required" : [ "default", "label", "name", "placeholder", "required", "secret" ], "type" : "object" }, "EngineWire" : { "properties" : { "fields" : { "items" : { "$ref" : "#/components/schemas/EngineFieldWire" }, "type" : "array" }, "id" : { "type" : "string" }, "label" : { "type" : "string" } }, "required" : [ "fields", "id", "label" ], "type" : "object" }, "EnginesResponse" : { "properties" : { "engines" : { "items" : { "$ref" : "#/components/schemas/EngineWire" }, "type" : "array" } }, "required" : [ "engines" ], "type" : "object" }, "ErrorBody" : { "properties" : { "error" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "required" : [ "error" ], "type" : "object" }, "ErrorDetail" : { "properties" : { "code" : { "type" : "string" }, "message" : { "type" : "string" }, "type" : { "type" : "string" } }, "required" : [ "code", "message", "type" ], "type" : "object" }, "EventAttendee" : { "properties" : { "displayName" : { "type" : "string" }, "email" : { "type" : "string" }, "isOptional" : { "type" : "boolean" }, "isOrganizer" : { "type" : "boolean" }, "isResource" : { "type" : "boolean" }, "response" : { "enum" : [ "NEEDS_ACTION", "ACCEPTED", "TENTATIVE", "DECLINED" ], "type" : "string" } }, "required" : [ "email", "isOptional", "isOrganizer", "isResource", "response" ], "type" : "object" }, "EventReceipt" : { "properties" : { "detail" : { "type" : "string" }, "label" : { "type" : "string" }, "status" : { "type" : "string" } }, "required" : [ "status" ], "type" : "object" }, "EventsResponse" : { "properties" : { "error" : { "type" : "string" }, "events" : { "items" : { "$ref" : "#/components/schemas/CalendarEvent" }, "type" : "array" } }, "required" : [ "events" ], "type" : "object" }, "Evidence" : { "properties" : { "conversation" : { "type" : "string" }, "refused" : { "items" : { "type" : "string" }, "type" : "array" }, "requests" : { "items" : { "$ref" : "#/components/schemas/EvidenceRequest" }, "type" : "array" } }, "required" : [ "conversation", "refused", "requests" ], "type" : "object" }, "EvidenceRequest" : { "properties" : { "detail" : { "type" : "string" }, "id" : { "type" : "string" }, "status" : { "type" : "string" }, "verb" : { "type" : "string" } }, "required" : [ "detail", "id", "status", "verb" ], "type" : "object" }, "Expected" : { "properties" : { "duty" : { "type" : "string" }, "lastCheckedAt" : { "format" : "date-time", "type" : "string" }, "violations" : { "format" : "int32", "type" : "integer" } }, "required" : [ "duty", "violations" ], "type" : "object" }, "ExportRequest" : { "properties" : { "labels" : { "items" : { "type" : "string" }, "type" : "array" }, "limit" : { "format" : "int32", "type" : "integer" }, "mode" : { "enum" : [ "SHAPE_ONLY", "WITH_VALUES" ], "type" : "string" }, "name" : { "type" : "string" }, "realm" : { "type" : "string" }, "source" : { "type" : "string" } }, "required" : [ "labels", "limit", "mode", "name", "realm" ], "type" : "object" }, "Fact" : { "allOf" : [ { "$ref" : "#/components/schemas/SensorEvent" }, { "properties" : { "confidence" : { "format" : "double", "type" : "number" }, "label" : { "type" : "string" }, "text" : { "type" : "string" } }, "type" : "object" } ], "required" : [ "text" ] }, "Fill" : { "properties" : { "budgetPerTick" : { "format" : "int64", "type" : "integer" }, "cypher" : { "type" : "string" }, "id" : { "type" : "string" }, "label" : { "type" : "string" }, "progress" : { "$ref" : "#/components/schemas/FillProgress" }, "userId" : { "type" : "string" } }, "required" : [ "budgetPerTick", "cypher", "id", "label", "progress", "userId" ], "type" : "object" }, "FillProgress" : { "properties" : { "createdAt" : { "format" : "int64", "type" : "integer" }, "lastError" : { "type" : "string" }, "lastTickAt" : { "format" : "int64", "type" : "integer" }, "liveCallsTotal" : { "format" : "int64", "type" : "integer" }, "state" : { "type" : "string" }, "ticks" : { "format" : "int64", "type" : "integer" } }, "required" : [ "createdAt", "liveCallsTotal", "state", "ticks" ], "type" : "object" }, "Firing" : { "properties" : { "cron" : { "type" : "string" }, "job" : { "type" : "string" }, "kind" : { "type" : "string" }, "nextAt" : { "format" : "date-time", "type" : "string" }, "postponedTo" : { "format" : "date-time", "type" : "string" }, "skipped" : { "type" : "boolean" }, "work" : { "type" : "string" }, "zone" : { "type" : "string" } }, "required" : [ "cron", "job", "kind", "skipped", "work", "zone" ], "type" : "object" }, "GoalListItem" : { "properties" : { "description" : { "type" : "string" }, "examples" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "name" : { "type" : "string" }, "outputType" : { "type" : "string" }, "tags" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true } }, "required" : [ "description", "examples", "name", "tags" ], "type" : "object" }, "HaltRequest" : { "properties" : { "reason" : { "type" : "string" } }, "type" : "object" }, "HaltResponse" : { "properties" : { "at" : { "type" : "string" }, "by" : { "type" : "string" }, "halted" : { "type" : "boolean" }, "reason" : { "type" : "string" } }, "required" : [ "halted" ], "type" : "object" }, "HandlerAvailable" : { "description" : "A realm-shipped handler available to adopt, which this user has not enabled.", "properties" : { "name" : { "type" : "string" }, "signalType" : { "type" : "string" } }, "required" : [ "name", "signalType" ], "type" : "object" }, "HandlerDryRunRequest" : { "description" : "A handler body to run observe-only, and what to run it against.", "properties" : { "sample" : { "additionalProperties" : { }, "description" : "A sample signal to bind INSTEAD of sampling the graph — for an event not yet received.", "type" : "object" }, "signalType" : { "description" : "The signal type to sample a real recent event from. Null or '*' means a cron tick.", "type" : "string" }, "source" : { "type" : "string" } }, "required" : [ "source" ], "type" : "object" }, "HandlerDryRunResponse" : { "description" : "The outcome of an observe-only handler run: what it saw, what it logged, and how it ended.", "properties" : { "error" : { "description" : "The failure message when the body threw. Serialized as null otherwise — consumers test for the key.", "type" : "string" }, "ok" : { "description" : "False when the body threw; `error` then carries the message.", "type" : "boolean" }, "output" : { "description" : "What the body RETURNED, when it returned something. A handler that ends with `return rows` and never logs is not silent — this is its result. Absent when the body returned nothing." }, "ranAgainst" : { "$ref" : "#/components/schemas/HandlerRanAgainst" }, "stdout" : { "description" : "Everything the body logged. The brief tells a handler to log every effect, so this IS the feedback surface.", "type" : "string" } }, "required" : [ "ok", "ranAgainst", "stdout" ], "type" : "object" }, "HandlerEnabledResponse" : { "description" : "Acknowledgement of an enable/disable, echoing the state now in force.", "properties" : { "enabled" : { "type" : "boolean" }, "name" : { "type" : "string" }, "ok" : { "type" : "boolean" } }, "required" : [ "enabled", "name", "ok" ], "type" : "object" }, "HandlerErrorResponse" : { "description" : "A refusal carrying only a human-readable reason.", "properties" : { "error" : { "description" : "What went wrong, in the terms the caller can act on.", "type" : "string" } }, "required" : [ "error" ], "type" : "object" }, "HandlerGenerateRequest" : { "description" : "An English description of a handler, optionally as a change to existing source.", "properties" : { "current" : { "description" : "When present, `english` is a CHANGE to this source — the round-trip an editor's Refine drives.", "type" : "string" }, "english" : { "type" : "string" }, "skills" : { "description" : "Skills to bundle. They are handed to the writing model as references — prompt contribution AND tools — so a realm's documented idioms are followed rather than re-derived.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "english" ], "type" : "object" }, "HandlerGenerateResponse" : { "description" : "Generated (or refined) handler source, with the tsc verdict on it.", "properties" : { "attempts" : { "description" : "1, or 2 when the model was handed its own type errors to fix.", "format" : "int32", "type" : "integer" }, "durationMs" : { "format" : "int64", "type" : "integer" }, "ok" : { "type" : "boolean" }, "source" : { "type" : "string" }, "valid" : { "type" : "boolean" }, "violations" : { "description" : "The compiler's errors, in the SOURCE's own line coordinates. Empty when `valid`.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "attempts", "durationMs", "ok", "source", "valid", "violations" ], "type" : "object" }, "HandlerListResponse" : { "description" : "The handlers this user has, and the realm-shipped ones they could adopt.", "properties" : { "available" : { "items" : { "$ref" : "#/components/schemas/HandlerAvailable" }, "type" : "array" }, "yours" : { "items" : { "$ref" : "#/components/schemas/HandlerListing" }, "type" : "array" } }, "required" : [ "available", "yours" ], "type" : "object" }, "HandlerListing" : { "description" : "A handler belonging to this user, with its triggers and whether it is live.", "properties" : { "active" : { "description" : "Whether it currently fires. A saved handler that is off changes nothing.", "type" : "boolean" }, "autonomous" : { "type" : "boolean" }, "inputTypeNames" : { "description" : "Domain types it consumes; empty means reaction-only (dispatcher, never planner).", "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "name" : { "type" : "string" }, "outputTypeName" : { "description" : "Domain type it returns, or 'void'.", "type" : "string" }, "schedule" : { "description" : "Its 6-field cron expression, or null when not scheduled.", "type" : "string" }, "signalType" : { "description" : "The signal type that fires it; '*' = none.", "type" : "string" }, "skills" : { "description" : "Skills bundled with it.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "active", "autonomous", "inputTypeNames", "name", "outputTypeName", "signalType", "skills" ], "type" : "object" }, "HandlerMutationResponse" : { "description" : "Whether the mutation landed, and what the server has to say about it.", "properties" : { "message" : { "type" : "string" }, "ok" : { "type" : "boolean" } }, "required" : [ "message", "ok" ], "type" : "object" }, "HandlerOpenResponse" : { "description" : "One handler's source and metadata, for round-tripping open → edit → save.", "properties" : { "autonomous" : { "type" : "boolean" }, "description" : { "type" : "string" }, "inputTypeNames" : { "description" : "Domain types it consumes; empty means reaction-only.", "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "name" : { "type" : "string" }, "outputTypeName" : { "description" : "Domain type it returns, or 'void'.", "type" : "string" }, "schedule" : { "type" : "string" }, "signalType" : { "type" : "string" }, "skills" : { "description" : "Skills bundled with it, round-tripped so an edit does not drop them.", "items" : { "type" : "string" }, "type" : "array" }, "source" : { "type" : "string" } }, "required" : [ "autonomous", "description", "inputTypeNames", "name", "outputTypeName", "signalType", "skills", "source" ], "type" : "object" }, "HandlerRanAgainst" : { "description" : "The signal a dry run bound, as sampled — not as requested.", "properties" : { "signalId" : { "type" : "string" }, "signalType" : { "type" : "string" } }, "required" : [ "signalId", "signalType" ], "type" : "object" }, "HandlerSaveRequest" : { "description" : "A handler to create or update, with its triggers.", "properties" : { "autonomous" : { "type" : "boolean" }, "description" : { "description" : "One line describing what it does. Defaults to the name.", "type" : "string" }, "inputTypeNames" : { "description" : "Domain types this action consumes. Declaring them makes it planner-chainable rather than reaction-only.", "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "name" : { "type" : "string" }, "outputTypeName" : { "description" : "Domain type the body returns, bound on the blackboard so later actions chain on it. 'void' for a side-effecting action.", "type" : "string" }, "schedule" : { "description" : "Optional 6-field cron expression; null = not scheduled.", "type" : "string" }, "signalType" : { "description" : "`Signal.typeName` (or simple name) that fires this handler; '*' = none.", "type" : "string" }, "skills" : { "description" : "Skills bundled with this agent, put in front of the model that writes and refines it.", "items" : { "type" : "string" }, "type" : "array" }, "source" : { "type" : "string" } }, "required" : [ "name", "source" ], "type" : "object" }, "HandlerScheduleResponse" : { "description" : "Acknowledgement of a schedule change, echoing the schedule now in force.", "properties" : { "name" : { "type" : "string" }, "ok" : { "type" : "boolean" }, "schedule" : { "description" : "The cron expression now in force, or null when the schedule was cleared.", "type" : "string" } }, "required" : [ "name", "ok" ], "type" : "object" }, "HandlerValidateRequest" : { "description" : "A handler body to type-check without saving or running it.", "properties" : { "source" : { "type" : "string" } }, "required" : [ "source" ], "type" : "object" }, "HandlerValidateResponse" : { "description" : "The tsc verdict on a handler body, without saving or running it.", "properties" : { "durationMs" : { "format" : "int64", "type" : "integer" }, "ok" : { "type" : "boolean" }, "valid" : { "type" : "boolean" }, "violations" : { "description" : "The compiler's errors, in the SOURCE's own line coordinates. Empty when `valid`.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "durationMs", "ok", "valid", "violations" ], "type" : "object" }, "Hint" : { "properties" : { "action" : { "$ref" : "#/components/schemas/HintAction" }, "body" : { "type" : "string" }, "category" : { "type" : "string" }, "icon" : { "type" : "string" }, "id" : { "type" : "string" }, "realm" : { "type" : "string" }, "surface" : { "type" : "string" }, "title" : { "type" : "string" } }, "required" : [ "body", "category", "id", "surface", "title" ], "type" : "object" }, "HintAction" : { "properties" : { "chatInput" : { "type" : "string" }, "label" : { "type" : "string" } }, "required" : [ "chatInput", "label" ], "type" : "object" }, "HomeLocationBody" : { "properties" : { "label" : { "type" : "string" }, "latitude" : { "format" : "double", "type" : "number" }, "longitude" : { "format" : "double", "type" : "number" } }, "type" : "object" }, "HomeLocationView" : { "properties" : { "label" : { "type" : "string" }, "latitude" : { "format" : "double", "type" : "number" }, "longitude" : { "format" : "double", "type" : "number" } }, "type" : "object" }, "InFlight" : { "properties" : { "deadline" : { "format" : "date-time", "type" : "string" }, "runId" : { "type" : "string" }, "startedAt" : { "format" : "date-time", "type" : "string" }, "work" : { "type" : "string" } }, "required" : [ "deadline", "runId", "startedAt", "work" ], "type" : "object" }, "InUseResponse" : { "properties" : { "allLocal" : { "type" : "boolean" }, "cloudProviders" : { "items" : { "type" : "string" }, "type" : "array" }, "models" : { "items" : { "$ref" : "#/components/schemas/ModelInUse" }, "type" : "array" }, "summary" : { "type" : "string" } }, "required" : [ "allLocal", "cloudProviders", "models", "summary" ], "type" : "object" }, "IngestJobList" : { "properties" : { "jobs" : { "items" : { "$ref" : "#/components/schemas/IngestJobView" }, "type" : "array" } }, "required" : [ "jobs" ], "type" : "object" }, "IngestJobMissing" : { "properties" : { "error" : { "type" : "string" } }, "required" : [ "error" ], "type" : "object" }, "IngestJobProgress" : { "properties" : { "done" : { "format" : "int32", "type" : "integer" }, "total" : { "format" : "int32", "type" : "integer" } }, "required" : [ "done", "total" ], "type" : "object" }, "IngestJobView" : { "properties" : { "chunks" : { "format" : "int32", "type" : "integer" }, "chunksWithoutEmbeddings" : { "format" : "int32", "type" : "integer" }, "error" : { "type" : "string" }, "id" : { "type" : "string" }, "name" : { "type" : "string" }, "progress" : { "$ref" : "#/components/schemas/IngestJobProgress" }, "resumes" : { "format" : "int32", "type" : "integer" }, "startedAt" : { "type" : "string" }, "state" : { "enum" : [ "queued", "waiting_for_memory", "converting", "writing", "embedding", "succeeded", "failed" ], "type" : "string" }, "title" : { "type" : "string" }, "updatedAt" : { "type" : "string" }, "uri" : { "type" : "string" } }, "required" : [ "id", "name", "resumes", "startedAt", "state", "updatedAt" ], "type" : "object" }, "IngestStatus" : { "description" : "The heap budget document ingests share, and the queue behind it", "properties" : { "budgetBytes" : { "description" : "Heap concurrent ingests may reserve", "format" : "int64", "type" : "integer" }, "inUseBytes" : { "description" : "Heap reserved by ingests running now", "format" : "int64", "type" : "integer" }, "waiting" : { "description" : "Ingests waiting for a running one to finish", "format" : "int32", "type" : "integer" } }, "required" : [ "budgetBytes", "inUseBytes", "waiting" ], "type" : "object" }, "IngestUnavailable" : { "properties" : { "embeddings" : { "additionalProperties" : { }, "type" : "object" }, "message" : { "type" : "string" }, "status" : { "type" : "string" } }, "required" : [ "embeddings", "message", "status" ], "type" : "object" }, "InstallRequest" : { "properties" : { "name" : { "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "InstalledResponse" : { "properties" : { "message" : { "type" : "string" }, "provisional" : { "type" : "boolean" }, "realm" : { "type" : "string" }, "unconfirmedDecisions" : { "format" : "int32", "type" : "integer" } }, "required" : [ "message", "provisional", "realm", "unconfirmedDecisions" ], "type" : "object" }, "InvokeRequest" : { "properties" : { "args" : { "additionalProperties" : { }, "type" : "object" }, "idempotencyKey" : { "type" : "string" } }, "required" : [ "args" ], "type" : "object" }, "JoinRequest" : { "properties" : { "channels" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "channels" ], "type" : "object" }, "JsonNode" : { "type" : "object" }, "JvmSnapshot" : { "properties" : { "cpuUsage" : { "format" : "double", "type" : "number" }, "gcPauseCount" : { "format" : "int64", "type" : "integer" }, "gcPauseTotalMillis" : { "format" : "double", "type" : "number" }, "memoryUsedBytes" : { "format" : "double", "type" : "number" }, "threadsLive" : { "format" : "double", "type" : "number" } }, "required" : [ "gcPauseCount", "gcPauseTotalMillis" ], "type" : "object" }, "KgAnnotationDiff" : { "description" : "One proposed property change, as it would be written.", "properties" : { "after" : { }, "before" : { "description" : "The value before the write, or null when the property is new." }, "identity" : { "description" : "The target's identity property value. Type depends on the label's identity property." }, "property" : { "type" : "string" } }, "required" : [ "property" ], "type" : "object" }, "KgAnnotationDryRunResponse" : { "description" : "A frozen annotation plan: what WOULD be written, with nothing written yet.", "properties" : { "diffs" : { "items" : { "$ref" : "#/components/schemas/KgAnnotationDiff" }, "type" : "array" }, "expiresAt" : { "description" : "When the frozen plan lapses, ISO-8601. Echo it back verbatim.", "type" : "string" }, "label" : { "type" : "string" }, "planId" : { "description" : "Pass this to /apply or /undo. Single-use and time-limited.", "type" : "string" }, "property" : { "type" : "string" }, "selected" : { "description" : "How many nodes the statement selected.", "format" : "int32", "type" : "integer" } }, "required" : [ "diffs", "expiresAt", "label", "planId", "property", "selected" ], "type" : "object" }, "KgAnnotationOutcomeResponse" : { "description" : "The result of applying or undoing a frozen plan.", "properties" : { "applied" : { "format" : "int32", "type" : "integer" }, "conflicted" : { "description" : "Targets that still exist but moved since the plan froze. Skipped, not forced.", "format" : "int32", "type" : "integer" }, "disappearedOrUnauthorized" : { "description" : "Targets that could not be re-bound in scope: deleted, re-owned or re-labeled. Deliberately ONE bucket — separating them would leak whether another tenant's data exists.", "format" : "int32", "type" : "integer" }, "planId" : { "type" : "string" }, "postImages" : { "items" : { "$ref" : "#/components/schemas/KgAnnotationPostImage" }, "type" : "array" }, "selected" : { "format" : "int32", "type" : "integer" } }, "required" : [ "applied", "conflicted", "disappearedOrUnauthorized", "planId", "postImages", "selected" ], "type" : "object" }, "KgAnnotationPostImage" : { "description" : "One committed post-image, read back inside the write transaction.", "properties" : { "auditId" : { "description" : "Audit record id for this individual write.", "type" : "string" }, "identity" : { }, "property" : { "type" : "string" }, "value" : { } }, "required" : [ "auditId", "property" ], "type" : "object" }, "KgAnswerAccepted" : { "description" : "Acknowledgement that a parked run accepted the owner's choice.", "properties" : { "choice" : { "type" : "string" }, "runId" : { "type" : "string" }, "state" : { "description" : "The state the run moved to as a result.", "type" : "string" } }, "required" : [ "choice", "runId", "state" ], "type" : "object" }, "KgAnswerRequest" : { "properties" : { "choice" : { "type" : "string" } }, "required" : [ "choice" ], "type" : "object" }, "KgAskRequest" : { "properties" : { "question" : { "type" : "string" } }, "required" : [ "question" ], "type" : "object" }, "KgAskScopeInfo" : { "description" : "A named scope: a declared realm set an ask can be narrowed to via `scope=`.", "properties" : { "description" : { "type" : "string" }, "name" : { "description" : "The scope's name — the value `scope=` accepts.", "type" : "string" }, "realms" : { "description" : "The realm names whose schema the scoped ask sees (plus the always-on core).", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "description", "name", "realms" ], "type" : "object" }, "KgBackgroundHandle" : { "description" : "A handle to a run started in the background.", "properties" : { "choices" : { "additionalProperties" : { }, "description" : "The question a parked run poses to its owner. Absent while running.", "type" : "object" }, "runId" : { "type" : "string" }, "state" : { "description" : "RUNNING, or WAITING_INPUT when the run parked on `choices`.", "type" : "string" } }, "required" : [ "runId", "state" ], "type" : "object" }, "KgBadChoiceResponse" : { "description" : "A rejected run answer, listing the choices this endpoint accepts.", "properties" : { "error" : { "type" : "string" }, "valid" : { "description" : "The accepted values for `choice`.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "error", "valid" ], "type" : "object" }, "KgBadRealmsResponse" : { "description" : "The scope named realms that are not installed; the installed ones travel with the refusal.", "properties" : { "error" : { "type" : "string" }, "installed" : { "description" : "The realm names actually installed in this world.", "items" : { "type" : "string" }, "type" : "array" }, "unknown" : { "description" : "The requested realm names no installed realm answers to.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "error", "installed", "unknown" ], "type" : "object" }, "KgContractColumn" : { "description" : "One drafted column, and whether its entry was read or inferred.", "properties" : { "evidence" : { "description" : "`declared` (read from the view) or `sampled` (inferred from rows).", "type" : "string" }, "logicalType" : { "description" : "ODCS logical type, present only when a sample agreed unanimously.", "type" : "string" }, "name" : { "type" : "string" }, "suggestions" : { "description" : "What the sample SUGGESTS but does not prove, as ODCS extension keys.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "evidence", "name", "suggestions" ], "type" : "object" }, "KgContractDisposition" : { "description" : "What the server actually did, separate from what it drafted.", "properties" : { "bound" : { "description" : "Whether the view now pins this contract in `observe` mode.", "type" : "boolean" }, "notes" : { "description" : "Human-readable notes: what was not done, and why.", "items" : { "type" : "string" }, "type" : "array" }, "sampleRows" : { "description" : "Rows read while sampling. Zero when the view was not run.", "format" : "int32", "type" : "integer" }, "sampleTruncated" : { "description" : "Whether sampling stopped at its row cap.", "type" : "boolean" }, "savedAs" : { "description" : "World-relative path written, or null when this was a preview.", "type" : "string" } }, "required" : [ "bound", "notes", "sampleRows", "sampleTruncated" ], "type" : "object" }, "KgContractRefusal" : { "description" : "A refusal to draft a contract, naming what about the view made it impossible.", "properties" : { "error" : { "type" : "string" } }, "required" : [ "error" ], "type" : "object" }, "KgCreateScopeRequest" : { "description" : "A named scope to declare: a world-tier focus the ask surface can be narrowed to.", "properties" : { "description" : { "type" : "string" }, "name" : { "description" : "Slug, `[a-z0-9][a-z0-9-]*` — the value `scope=` will accept. No `+`: unencoded it decodes to a space in a query parameter.", "type" : "string" }, "realms" : { "description" : "Installed realm names whose schema the scope's asks see.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "description", "name", "realms" ], "type" : "object" }, "KgDecorationReport" : { "description" : "What one decoration tick did.", "properties" : { "candidates" : { "description" : "Stale nodes this tick picked up. 0 with an `error` means the decorator is unknown.", "format" : "int32", "type" : "integer" }, "decorated" : { "format" : "int32", "type" : "integer" }, "decorator" : { "type" : "string" }, "error" : { "description" : "Why the tick could not complete, or null. Always present.", "type" : "string" }, "failed" : { "format" : "int32", "type" : "integer" }, "skipped" : { "format" : "int32", "type" : "integer" } }, "required" : [ "candidates", "decorated", "decorator", "failed", "skipped" ], "type" : "object" }, "KgDecoratorInfo" : { "description" : "A registered node decorator and the cadence it runs on.", "properties" : { "batchSize" : { "description" : "Most candidates one tick will process.", "format" : "int32", "type" : "integer" }, "name" : { "type" : "string" }, "refreshAfter" : { "description" : "How stale a node must be before it is a candidate again, or `never`.", "type" : "string" }, "stampProperty" : { "description" : "The property stamped on a node once decorated — how staleness is judged.", "type" : "string" }, "targetLabels" : { "description" : "Labels this decorator considers as candidates.", "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "tickInterval" : { "description" : "How often the scheduled tick fires, ISO-8601 duration.", "type" : "string" } }, "required" : [ "batchSize", "name", "refreshAfter", "stampProperty", "targetLabels", "tickInterval" ], "type" : "object" }, "KgDecoratorListResponse" : { "description" : "The registered node decorators.", "properties" : { "decorators" : { "items" : { "$ref" : "#/components/schemas/KgDecoratorInfo" }, "type" : "array" } }, "required" : [ "decorators" ], "type" : "object" }, "KgDeleteViewResponse" : { "description" : "A user-authored view was deleted.", "properties" : { "name" : { "type" : "string" }, "status" : { "description" : "Always `deleted`.", "type" : "string" } }, "required" : [ "name", "status" ], "type" : "object" }, "KgDerivation" : { "properties" : { "elementId" : { "type" : "string" }, "props" : { "additionalProperties" : { }, "type" : "object" }, "round" : { "format" : "int32", "type" : "integer" }, "rule" : { "format" : "int32", "type" : "integer" }, "trace" : { "items" : { "$ref" : "#/components/schemas/KgDerivedFiring" }, "type" : "array" } }, "required" : [ "elementId", "props", "round", "rule", "trace" ], "type" : "object" }, "KgDeriveDemandWire" : { "properties" : { "description" : { "type" : "string" }, "materialize" : { "type" : "string" } }, "required" : [ "description", "materialize" ], "type" : "object" }, "KgDeriveRequest" : { "properties" : { "cypher" : { "type" : "string" }, "derives" : { "type" : "string" }, "description" : { "type" : "string" }, "name" : { "type" : "string" }, "paramSpecs" : { "additionalProperties" : { "$ref" : "#/components/schemas/ViewParamSpec" }, "type" : "object" }, "params" : { "additionalProperties" : { }, "type" : "object" }, "requires" : { "items" : { "$ref" : "#/components/schemas/KgDeriveDemandWire" }, "type" : "array" }, "rules" : { "items" : { "$ref" : "#/components/schemas/KgDeriveRuleWire" }, "type" : "array" } }, "required" : [ "cypher", "derives", "description", "paramSpecs", "params", "requires", "rules" ], "type" : "object" }, "KgDeriveResponse" : { "properties" : { "derived" : { "items" : { "$ref" : "#/components/schemas/KgDerivedLabel" }, "type" : "array" }, "result" : { "$ref" : "#/components/schemas/KgQueryResult" } }, "required" : [ "derived", "result" ], "type" : "object" }, "KgDeriveRuleWire" : { "properties" : { "derive" : { "type" : "string" }, "from" : { "type" : "string" } }, "required" : [ "derive", "from" ], "type" : "object" }, "KgDerivedFiring" : { "properties" : { "props" : { "additionalProperties" : { }, "type" : "object" }, "round" : { "format" : "int32", "type" : "integer" }, "rule" : { "format" : "int32", "type" : "integer" } }, "required" : [ "props", "round", "rule" ], "type" : "object" }, "KgDerivedLabel" : { "properties" : { "derivations" : { "items" : { "$ref" : "#/components/schemas/KgDerivation" }, "type" : "array" }, "label" : { "type" : "string" }, "members" : { "format" : "int32", "type" : "integer" }, "rounds" : { "format" : "int32", "type" : "integer" }, "ruleSet" : { "type" : "string" }, "truncated" : { "type" : "boolean" } }, "required" : [ "derivations", "label", "members", "rounds", "ruleSet", "truncated" ], "type" : "object" }, "KgErrorResponse" : { "description" : "A refusal carrying only a human-readable reason.", "properties" : { "error" : { "description" : "What went wrong, in the terms the caller can act on.", "type" : "string" } }, "required" : [ "error" ], "type" : "object" }, "KgExecuteRequest" : { "properties" : { "args" : { "additionalProperties" : { }, "description" : "Arguments for `params`. A blank value means not supplied, so the default applies.", "type" : "object" }, "captureAs" : { "description" : "Capture the result set as this named scope; reference it later as (x:`$name`). The statement must RETURN one labelled node variable. Synchronous mode only.", "type" : "string" }, "cypher" : { "type" : "string" }, "params" : { "additionalProperties" : { "$ref" : "#/components/schemas/ViewParamSpec" }, "description" : "Declared parameters for the cypher, as a view declares them. Each `$name` is substituted from `args` merged over its default, exactly as when a saved view runs.", "type" : "object" } }, "required" : [ "cypher" ], "type" : "object" }, "KgGenerateContractRequest" : { "description" : "How to draft an ODCS contract for a named view, and how far to go with it.", "properties" : { "args" : { "additionalProperties" : { }, "description" : "Arguments for a parameterized view. Used only when sampling.", "type" : "object" }, "bind" : { "description" : "Also pin the view to the new contract in `observe` mode. Requires `persist`.", "type" : "boolean" }, "persist" : { "description" : "Write the draft into the world. False previews it and writes nothing.", "type" : "boolean" }, "sample" : { "description" : "Run the view under a row cap to infer types and suggestions. Off by default: generation reads the declaration only unless asked to touch data.", "type" : "boolean" } }, "type" : "object" }, "KgGenerateContractResponse" : { "description" : "A drafted ODCS contract for a named view, in `draft` status and unreviewed.", "properties" : { "columns" : { "items" : { "$ref" : "#/components/schemas/KgContractColumn" }, "type" : "array" }, "contractId" : { "type" : "string" }, "disposition" : { "$ref" : "#/components/schemas/KgContractDisposition", "description" : "What was written and bound, and what an author still has to do." }, "mode" : { "description" : "`declaration` or `sample` — how much of this draft came from data.", "type" : "string" }, "status" : { "description" : "ODCS status of the generated document. Always `draft`.", "type" : "string" }, "version" : { "type" : "string" }, "view" : { "type" : "string" }, "yaml" : { "description" : "The contract document. Review this before promoting anything.", "type" : "string" } }, "required" : [ "columns", "contractId", "disposition", "mode", "status", "version", "view", "yaml" ], "type" : "object" }, "KgGenerateRequest" : { "description" : "A question to write Cypher for, and whether a saved view that answers it may stand in.", "properties" : { "preferViews" : { "description" : "Consult the saved-view catalogue first (default true): a question a curated view already answers comes back as that view's invocation, with `view` set. False generates regardless.", "type" : "boolean" }, "question" : { "type" : "string" } }, "required" : [ "question" ], "type" : "object" }, "KgGenerateResponse" : { "description" : "Generated cypher and what the engine will do with it, without running it.", "properties" : { "attempts" : { "description" : "How many generate-validate rounds it took.", "format" : "int32", "type" : "integer" }, "cypher" : { "type" : "string" }, "durationMs" : { "format" : "int64", "type" : "integer" }, "explain" : { "description" : "What the engine will do when this runs. Best-effort; never fails the call.", "type" : "string" }, "question" : { "type" : "string" }, "valid" : { "description" : "Whether the final attempt passed the strict preflight.", "type" : "boolean" }, "view" : { "$ref" : "#/components/schemas/KgViewMatch", "description" : "Present when a saved view already answers the question: `cypher` is then that view's invocation, `attempts` is 0, and nothing was generated. Absent when the Cypher was written for this question." }, "violations" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "attempts", "cypher", "durationMs", "explain", "question", "valid", "violations" ], "type" : "object" }, "KgInFlightRun" : { "description" : "A virtual-cypher run currently executing for the acting user.", "properties" : { "cypher" : { "type" : "string" }, "runId" : { "type" : "string" }, "startedAt" : { "description" : "Epoch milliseconds at which the run started.", "format" : "int64", "type" : "integer" } }, "required" : [ "cypher", "runId", "startedAt" ], "type" : "object" }, "KgInvokeViewRequest" : { "properties" : { "args" : { "additionalProperties" : { }, "type" : "object" } }, "type" : "object" }, "KgKillResponse" : { "description" : "The outcome of a kill request.", "properties" : { "killed" : { "description" : "False when the run had already settled, or was never the caller's.", "type" : "boolean" }, "runId" : { "type" : "string" } }, "required" : [ "killed", "runId" ], "type" : "object" }, "KgPropertyValuesResponse" : { "properties" : { "enumerable" : { "description" : "False when the source cannot be asked at all — NOT the same as an empty set.", "type" : "boolean" }, "label" : { "type" : "string" }, "property" : { "type" : "string" }, "reason" : { "type" : "string" }, "tooMany" : { "$ref" : "#/components/schemas/KgValueOverflow", "description" : "Present when the domain is WIDER than max — its presence IS the signal." }, "values" : { "description" : "The closed set, when it fits within the property's declared max.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "enumerable", "label", "property" ], "type" : "object" }, "KgQueryResult" : { "description" : "The outcome of a virtual-cypher query: rows, the cypher that produced them, and what it cost.", "properties" : { "apiCallLog" : { "description" : "The actual calls as `producer(keys)`, in order — fan-out is visible here.", "items" : { "type" : "string" }, "type" : "array" }, "apiCalls" : { "description" : "External fetches the executor made. 0 means everything was cached or local.", "format" : "int32", "type" : "integer" }, "capturedScope" : { "$ref" : "#/components/schemas/KgScopeInfo", "description" : "The scope this result set froze into — present only on a capturing execute." }, "cypher" : { "description" : "The cypher that actually ran, after scope rewriting.", "type" : "string" }, "dataContract" : { "$ref" : "#/components/schemas/DataContractEvaluation", "description" : "The pinned ODCS identity and invocation verdict, for a contracted named view only." }, "durationMs" : { "description" : "Total: bridge-resolve plus materialize plus read.", "format" : "int64", "type" : "integer" }, "error" : { "description" : "Why the query failed, or null when it did not.", "type" : "string" }, "hint" : { "description" : "What to try instead. Accompanies an empty result only.", "type" : "string" }, "llmCallLog" : { "description" : "The actual LLM calls (kg-ask and agg-*), in order.", "items" : { "type" : "string" }, "type" : "array" }, "llmCalls" : { "description" : "LLM calls: the generation plus any aggregate reductions.", "format" : "int32", "type" : "integer" }, "question" : { "description" : "The question asked, echoed back. Present only for `/ask`.", "type" : "string" }, "reason" : { "description" : "Typed outcome when this was not a clean answer — UNBOUNDED, NOT_IN_GRAPH, MISSING_ATTRIBUTE, DISCONNECTED or INTERNAL_ERROR. Absent on a real answer, so a caller can tell 'cannot answer' from a genuine zero without reading the hint text.", "type" : "string" }, "rowCount" : { "format" : "int32", "type" : "integer" }, "rows" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" }, "run" : { "$ref" : "#/components/schemas/KgRunRef" }, "warnings" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "apiCallLog", "apiCalls", "cypher", "durationMs", "llmCallLog", "llmCalls", "rowCount", "rows", "warnings" ], "type" : "object" }, "KgRefineRequest" : { "properties" : { "cypher" : { "type" : "string" }, "instruction" : { "type" : "string" } }, "required" : [ "cypher", "instruction" ], "type" : "object" }, "KgRefreshViewResponse" : { "description" : "Whether a materialised view's cache was recomputed.", "properties" : { "name" : { "type" : "string" }, "refreshed" : { "description" : "False for a regular or unknown view — nothing was recomputed.", "type" : "boolean" } }, "required" : [ "name", "refreshed" ], "type" : "object" }, "KgReprojectResponse" : { "description" : "How much of a user's stored propositions were re-projected into graph edges.", "properties" : { "attempted" : { "description" : "Relationships the projection attempted.", "format" : "int32", "type" : "integer" }, "durationMs" : { "format" : "int64", "type" : "integer" }, "persisted" : { "description" : "Relationships actually persisted.", "format" : "int32", "type" : "integer" }, "propositions" : { "description" : "Propositions read for this context.", "format" : "int32", "type" : "integer" }, "username" : { "type" : "string" } }, "required" : [ "attempted", "durationMs", "persisted", "propositions", "username" ], "type" : "object" }, "KgRunConflictResponse" : { "description" : "The run was not awaiting input; its actual state travels with the refusal.", "properties" : { "detail" : { "description" : "Why it is in that state, when anything was recorded. Null otherwise.", "type" : "string" }, "error" : { "type" : "string" }, "state" : { "description" : "The run's real state: RUNNING, COMPLETED, KILLED, FAILED, CANCELLED or EXPIRED.", "type" : "string" } }, "required" : [ "error", "state" ], "type" : "object" }, "KgRunRef" : { "description" : "A watchable run handle. Its presence means the rows are 'not yet', not 'none'.", "properties" : { "answer" : { "description" : "Where to send the owner's pick for a parked run. Absent while running.", "type" : "string" }, "choices" : { "additionalProperties" : { }, "description" : "The `{kind, question, options, context}` payload when parked.", "type" : "object" }, "kill" : { "description" : "Where to stop the run. Absent when parked — nothing is executing to kill.", "type" : "string" }, "poll" : { "description" : "Where to poll for state and, once settled, the result.", "type" : "string" }, "runId" : { "type" : "string" }, "state" : { "description" : "RUNNING (materializing now) or WAITING_INPUT (parked on `choices`).", "type" : "string" } }, "required" : [ "poll", "runId", "state" ], "type" : "object" }, "KgRunState" : { "description" : "The state of a background run, with its result once it has settled.", "properties" : { "choices" : { "additionalProperties" : { }, "description" : "The question a parked run poses to its owner.", "type" : "object" }, "cypher" : { "type" : "string" }, "detail" : { "description" : "Why the run ended as it did, when anything was recorded.", "type" : "string" }, "endedAt" : { "format" : "int64", "type" : "integer" }, "expiresAt" : { "description" : "Epoch milliseconds at which a parked run lapses into EXPIRED.", "format" : "int64", "type" : "integer" }, "result" : { "$ref" : "#/components/schemas/KgQueryResult" }, "runId" : { "type" : "string" }, "startedAt" : { "format" : "int64", "type" : "integer" }, "state" : { "type" : "string" } }, "required" : [ "cypher", "runId", "startedAt", "state" ], "type" : "object" }, "KgSaveViewRejection" : { "description" : "A view was refused: a bad name, an unrunnable body, or a name already taken.", "properties" : { "error" : { "type" : "string" }, "name" : { "type" : "string" }, "ok" : { "type" : "boolean" }, "violations" : { "description" : "Preflight defects when the body names shapes the schema contradicts.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "ok" ], "type" : "object" }, "KgSaveViewRequest" : { "properties" : { "cypher" : { "type" : "string" }, "description" : { "type" : "string" }, "materialized" : { "type" : "boolean" }, "name" : { "type" : "string" }, "outputLabel" : { "type" : "string" }, "params" : { "additionalProperties" : { "$ref" : "#/components/schemas/ViewParamSpec" }, "type" : "object" }, "ttl" : { "type" : "string" } }, "required" : [ "cypher", "name" ], "type" : "object" }, "KgSaveViewResponse" : { "description" : "A view was saved.", "properties" : { "name" : { "type" : "string" }, "note" : { "description" : "Why the stored query differs from the one sent", "type" : "string" }, "ok" : { "type" : "boolean" }, "savedCypher" : { "description" : "The stored query, when promotion inlined captured scopes into it", "type" : "string" } }, "required" : [ "name", "ok" ], "type" : "object" }, "KgSchemaLabel" : { "description" : "A node label and its sampled property shape.", "properties" : { "anchor" : { "description" : "True when this label may open a MATCH pattern bare — a real read, or a virtual population implicitly bound by user tenancy. False means it is reachable only by traversal from a bound anchor; an editor should not offer it at first position. Defaults true so an older client reading a newer appliance loses nothing.", "type" : "boolean" }, "description" : { "description" : "The declared definition of the type this label names, verbatim from the realm's own registry — for an editor to show on hover. Null for core/introspected labels, which declare none.", "type" : "string" }, "exhaustive" : { "description" : "True when every node carrying this label was inspected, so an absent property genuinely does not exist here. False means the sample was capped — evidence of what exists, and no evidence at all about what does not.", "type" : "boolean" }, "label" : { "type" : "string" }, "properties" : { "items" : { "$ref" : "#/components/schemas/KgSchemaProperty" }, "type" : "array" }, "realm" : { "description" : "The realm that declared this label's type. Null means core — the world's own types or the host's.", "type" : "string" }, "sampleCount" : { "description" : "How many nodes were sampled when inferring the properties.", "format" : "int32", "type" : "integer" } }, "required" : [ "anchor", "exhaustive", "label", "properties", "sampleCount" ], "type" : "object" }, "KgSchemaProperty" : { "description" : "A property observed on nodes carrying a label.", "properties" : { "alternateKey" : { "description" : "True when the realm's type declares this property as an ALTERNATE KEY: it identifies the same record as the identity does, in the vocabulary the source's own readers use. A policy's `policy_identifier` is its identity; its `policy_number` is what a view shows and what a client will try to join on. Both name the same policy. Unlike the identity, an alternate key is not the dedupe key and is not required on write, so a type may declare several. Defaults false.", "type" : "boolean" }, "description" : { "description" : "The property's DECLARED description, verbatim from the realm's registry — for an editor to show on hover. Null where the declaration documents nothing.", "type" : "string" }, "identity" : { "description" : "True when the realm's type declares this property as the node's IDENTITY. Two columns denote the same thing only when both project the identity of the same label; matching names prove nothing, and a client that joins on them will relate records that are not related. Defaults false so an older client reading a newer appliance loses nothing, and so an undeclared property is never mistaken for a key.", "type" : "boolean" }, "name" : { "type" : "string" }, "sparse" : { "description" : "True when the property was missing from a non-trivial fraction of the sample.", "type" : "boolean" }, "type" : { "description" : "Inferred type tag: string, long, datetime, list, any, …", "type" : "string" } }, "required" : [ "alternateKey", "identity", "name", "sparse", "type" ], "type" : "object" }, "KgSchemaRelationship" : { "description" : "A (from, type, to) triple observed in the world subgraph.", "properties" : { "count" : { "description" : "Approximate occurrence count, for ranking.", "format" : "int64", "type" : "integer" }, "from" : { "type" : "string" }, "to" : { "type" : "string" }, "type" : { "type" : "string" } }, "required" : [ "count", "from", "to", "type" ], "type" : "object" }, "KgSchemaResponse" : { "description" : "Labels, their properties, and relationship triples reachable by the acting user.", "properties" : { "labels" : { "items" : { "$ref" : "#/components/schemas/KgSchemaLabel" }, "type" : "array" }, "refreshedAt" : { "description" : "When the snapshot was taken, ISO-8601. Absent when there is no snapshot.", "type" : "string" }, "relationships" : { "items" : { "$ref" : "#/components/schemas/KgSchemaRelationship" }, "type" : "array" } }, "required" : [ "labels", "relationships" ], "type" : "object" }, "KgScopeDeleteResponse" : { "description" : "The outcome of deleting a captured scope.", "properties" : { "deleted" : { "type" : "boolean" }, "name" : { "type" : "string" } }, "required" : [ "deleted", "name" ], "type" : "object" }, "KgScopeInfo" : { "description" : "A captured query scope: a frozen result set referenced in a later query as (x:`$name`).", "properties" : { "capturedAt" : { "description" : "When the membership froze, ISO-8601.", "type" : "string" }, "expiresAt" : { "description" : "When the scope lapses, ISO-8601 — null means PINNED (kept until deleted).", "type" : "string" }, "members" : { "description" : "How many members the capture froze. Membership is frozen; values stay live.", "format" : "int64", "type" : "integer" }, "name" : { "type" : "string" }, "outputLabel" : { "description" : "The node label later references bind with.", "type" : "string" }, "statement" : { "description" : "The statement that produced the capture — the scope's provenance.", "type" : "string" } }, "required" : [ "capturedAt", "members", "name", "outputLabel", "statement" ], "type" : "object" }, "KgScopeListResponse" : { "description" : "The acting user's live captured scopes, newest first.", "properties" : { "scopes" : { "items" : { "$ref" : "#/components/schemas/KgScopeInfo" }, "type" : "array" } }, "required" : [ "scopes" ], "type" : "object" }, "KgUnknownScopeResponse" : { "description" : "The named scope does not exist in the acting user's world; the ones that do travel with the refusal.", "properties" : { "available" : { "description" : "The scope names this world declares (its focuses).", "items" : { "type" : "string" }, "type" : "array" }, "error" : { "type" : "string" } }, "required" : [ "available", "error" ], "type" : "object" }, "KgValidationResponse" : { "description" : "The result of validating cypher against the schema without executing it.", "properties" : { "message" : { "description" : "A single human-readable summary, or null when there is nothing to say.", "type" : "string" }, "ok" : { "type" : "boolean" }, "violations" : { "description" : "What the schema contradicts, one entry per defect.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "ok", "violations" ], "type" : "object" }, "KgValueOverflow" : { "properties" : { "count" : { "description" : "How many distinct values exist. Null when the source could not be counted.", "format" : "int32", "type" : "integer" }, "max" : { "description" : "The cap that was exceeded — the property's declared `max`.", "format" : "int32", "type" : "integer" }, "sample" : { "description" : "A few values, to show the SHAPE of the domain. NEVER treat this as the set.", "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "max", "sample" ], "type" : "object" }, "KgViewInvocationResponse" : { "description" : "The runnable cypher for a saved view invoked with the given arguments.", "properties" : { "cypher" : { "description" : "Run this through `/execute`, so a view uses the same engine as any other query.", "type" : "string" }, "name" : { "type" : "string" } }, "required" : [ "cypher", "name" ], "type" : "object" }, "KgViewMatch" : { "description" : "The saved view a question was routed to instead of generating Cypher.", "properties" : { "args" : { "additionalProperties" : { }, "description" : "The arguments the selector bound from the question, by parameter name.", "type" : "object" }, "name" : { "type" : "string" }, "reason" : { "description" : "The selector's one line on why this view.", "type" : "string" } }, "required" : [ "args", "name" ], "type" : "object" }, "LearnApiRequest" : { "description" : "An API to introspect", "properties" : { "type" : { "default" : "openapi", "description" : "openapi (the default) or graphql", "type" : "string" }, "url" : { "description" : "The spec URL — an OpenAPI document or a GraphQL endpoint", "type" : "string" } }, "required" : [ "url" ], "type" : "object" }, "LearnRequest" : { "properties" : { "consent" : { "type" : "string" }, "purpose" : { "type" : "string" } }, "type" : "object" }, "LensChatRequest" : { "properties" : { "conversationId" : { "type" : "string" }, "english" : { "type" : "string" }, "lensId" : { "type" : "string" }, "question" : { "type" : "string" }, "script" : { "type" : "string" } }, "required" : [ "question" ], "type" : "object" }, "LensParam" : { "properties" : { "default" : { }, "label" : { "type" : "string" }, "name" : { "type" : "string" }, "required" : { "type" : "boolean" }, "type" : { "enum" : [ "STRING", "INT", "DATE", "DURATION", "BOOLEAN" ], "type" : "string" } }, "required" : [ "label", "name", "required", "type" ], "type" : "object" }, "LlmConfig" : { "properties" : { "description" : { "type" : "string" }, "model" : { "type" : "string" }, "reasoningEffort" : { "type" : "string" }, "role" : { "type" : "string" }, "temperature" : { "format" : "double", "type" : "number" } }, "type" : "object" }, "LogEntry" : { "properties" : { "level" : { "type" : "string" }, "logger" : { "type" : "string" }, "message" : { "type" : "string" }, "thread" : { "type" : "string" }, "timestamp" : { "format" : "int64", "type" : "integer" } }, "required" : [ "level", "logger", "message", "thread", "timestamp" ], "type" : "object" }, "LogTail" : { "properties" : { "bufferSize" : { "format" : "int32", "type" : "integer" }, "entries" : { "items" : { "$ref" : "#/components/schemas/LogEntry" }, "type" : "array" }, "truncated" : { "type" : "boolean" } }, "required" : [ "bufferSize", "entries", "truncated" ], "type" : "object" }, "McpModeRequest" : { "description" : "The mode a connected coding agent runs under", "properties" : { "mode" : { "description" : "ASSISTANT or DEVELOPER", "enum" : [ "ASSISTANT", "DEVELOPER" ], "type" : "string" } }, "required" : [ "mode" ], "type" : "object" }, "McpServerInfo" : { "properties" : { "description" : { "type" : "string" }, "name" : { "type" : "string" }, "toolCount" : { "format" : "int32", "type" : "integer" }, "toolNames" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "name", "toolCount", "toolNames" ], "type" : "object" }, "MemoryStatus" : { "description" : "The JVM heap and the container it runs in", "properties" : { "containerLimitBytes" : { "description" : "The container's memory limit from cgroup v2. Null when unlimited or unreadable.", "format" : "int64", "type" : "integer" }, "containerUsedBytes" : { "description" : "Memory the container uses now, from cgroup v2. Null when unreadable.", "format" : "int64", "type" : "integer" }, "heapAfterGcBytes" : { "description" : "Heap in use straight after the most recent garbage collection — the closest cheap reading of what the app actually holds. Null until the first collection.", "format" : "int64", "type" : "integer" }, "heapMaxBytes" : { "description" : "The heap ceiling (-Xmx, or MaxRAMPercentage of the container). Null if the JVM sets none.", "format" : "int64", "type" : "integer" }, "heapUsedBytes" : { "description" : "Heap in use now, garbage included; rises and falls between collections", "format" : "int64", "type" : "integer" } }, "required" : [ "heapUsedBytes" ], "type" : "object" }, "Message" : { "properties" : { "content" : { "type" : "string" }, "role" : { "type" : "string" } }, "required" : [ "content", "role" ], "type" : "object" }, "MintRequest" : { "properties" : { "agents" : { "items" : { "type" : "string" }, "type" : "array" }, "name" : { "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "Model" : { "properties" : { "created" : { "format" : "int64", "type" : "integer" }, "id" : { "type" : "string" }, "object" : { "type" : "string" }, "owned_by" : { "type" : "string" } }, "required" : [ "created", "id", "object", "owned_by" ], "type" : "object" }, "ModelInUse" : { "properties" : { "local" : { "type" : "boolean" }, "model" : { "type" : "string" }, "provider" : { "type" : "string" }, "purpose" : { "type" : "string" } }, "required" : [ "local", "purpose" ], "type" : "object" }, "ModelList" : { "properties" : { "data" : { "items" : { "$ref" : "#/components/schemas/Model" }, "type" : "array" }, "object" : { "type" : "string" } }, "required" : [ "data", "object" ], "type" : "object" }, "ModelRunnerActivity" : { "description" : "Docker Model Runner's embedding model, as its own process list reports it", "properties" : { "busy" : { "description" : "Whether that model is serving a request now. It runs on the host, outside the app's container, so its CPU is not in the cpu figures.", "type" : "boolean" }, "loaded" : { "description" : "Whether an embedding model is loaded. Model Runner loads one on the first request and unloads it when idle.", "type" : "boolean" } }, "required" : [ "busy", "loaded" ], "type" : "object" }, "NewDuty" : { "properties" : { "every" : { "type" : "string" }, "holds" : { "type" : "string" }, "name" : { "type" : "string" }, "text" : { "type" : "string" } }, "required" : [ "holds", "name", "text" ], "type" : "object" }, "NewRoleRequest" : { "properties" : { "description" : { "description" : "What the role is for", "type" : "string" }, "id" : { "description" : "Lowercase letters, digits and underscores, starting with a letter", "type" : "string" }, "model" : { "description" : "The model it uses", "type" : "string" } }, "required" : [ "description", "id", "model" ], "type" : "object" }, "NodeRequest" : { "properties" : { "displayName" : { "type" : "string" }, "id" : { "type" : "string" }, "label" : { "type" : "string" }, "properties" : { "additionalProperties" : { }, "type" : "object" } }, "required" : [ "id", "label", "properties" ], "type" : "object" }, "Notification" : { "properties" : { "actionKind" : { "enum" : [ "DRAFT_REPLY", "SEND_PREP", "UPDATE_RECORD", "SCHEDULE_BLOCK", "NOTIFY_PERSON", "ACK_ONLY", "CONFIRM_IDENTITY_LINK", "DECIDE_REQUEST" ], "type" : "string" }, "confidence" : { "format" : "double", "type" : "number" }, "consequenceOfInaction" : { "type" : "string" }, "createdAt" : { "format" : "date-time", "type" : "string" }, "createdBy" : { "type" : "string" }, "deadline" : { "format" : "date-time", "type" : "string" }, "event" : { "type" : "string" }, "id" : { "type" : "string" }, "kind" : { "enum" : [ "ORIGINAL", "UPDATE", "CANCELLATION", "COMPLETION" ], "type" : "string" }, "read" : { "type" : "boolean" }, "recommendation" : { "type" : "string" }, "source" : { "type" : "string" }, "sourceSignalIds" : { "items" : { "type" : "string" }, "type" : "array" }, "sources" : { "items" : { "$ref" : "#/components/schemas/NotificationSource" }, "type" : "array" }, "supersedes" : { "items" : { "type" : "string" }, "type" : "array" }, "tier" : { "enum" : [ "AMBIENT", "DEFERRED", "TIMELY", "INTERRUPTIVE", "ACTING", "ESCALATING" ], "type" : "string" }, "url" : { "type" : "string" }, "userId" : { "type" : "string" }, "whyItMatters" : { "type" : "string" } }, "required" : [ "createdAt", "createdBy", "event", "id", "kind", "read", "source", "sourceSignalIds", "sources", "supersedes", "tier", "userId" ], "type" : "object" }, "NotificationNode" : { "properties" : { "actionKind" : { "type" : "string" }, "confidence" : { "format" : "double", "type" : "number" }, "consequenceOfInaction" : { "type" : "string" }, "created" : { "format" : "date-time", "type" : "string" }, "createdBy" : { "type" : "string" }, "deadline" : { "format" : "date-time", "type" : "string" }, "event" : { "type" : "string" }, "id" : { "type" : "string" }, "kind" : { "type" : "string" }, "read" : { "type" : "boolean" }, "recommendation" : { "type" : "string" }, "source" : { "type" : "string" }, "sourceSignalIdsJson" : { "type" : "string" }, "sourcesJson" : { "type" : "string" }, "supersedesJson" : { "type" : "string" }, "tier" : { "type" : "string" }, "url" : { "type" : "string" }, "userId" : { "type" : "string" }, "whyItMatters" : { "type" : "string" } }, "required" : [ "created", "createdBy", "event", "id", "kind", "read", "source", "sourceSignalIdsJson", "sourcesJson", "supersedesJson", "tier", "userId" ], "type" : "object" }, "NotificationRoutingConfig" : { "properties" : { "quietHours" : { "$ref" : "#/components/schemas/QuietHoursConfig" }, "tierChannels" : { "additionalProperties" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "type" : "object" } }, "required" : [ "tierChannels" ], "type" : "object" }, "NotificationSource" : { "properties" : { "displayLabel" : { "type" : "string" }, "id" : { "type" : "string" }, "kind" : { "type" : "string" }, "typeName" : { "type" : "string" }, "url" : { "type" : "string" } }, "required" : [ "displayLabel", "id", "kind", "typeName" ], "type" : "object" }, "OfferedChannel" : { "properties" : { "apps" : { "format" : "int32", "type" : "integer" }, "channel" : { "type" : "string" }, "views" : { "format" : "int32", "type" : "integer" } }, "required" : [ "apps", "channel", "views" ], "type" : "object" }, "OnboardingRequest" : { "properties" : { "buildMeApp" : { "type" : "boolean" }, "lookbackDays" : { "format" : "int32", "type" : "integer" }, "sources" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "buildMeApp", "lookbackDays", "sources" ], "type" : "object" }, "OnboardingSource" : { "properties" : { "available" : { "type" : "boolean" }, "id" : { "type" : "string" }, "label" : { "type" : "string" } }, "required" : [ "available", "id", "label" ], "type" : "object" }, "OnboardingStartResponse" : { "properties" : { "jobId" : { "type" : "string" }, "status" : { "type" : "string" } }, "required" : [ "jobId", "status" ], "type" : "object" }, "OnboardingStatusResponse" : { "properties" : { "error" : { "type" : "string" }, "jobId" : { "type" : "string" }, "progress" : { "type" : "string" }, "status" : { "type" : "string" } }, "required" : [ "jobId", "status" ], "type" : "object" }, "PostMessageRequest" : { "properties" : { "attachments" : { "items" : { "$ref" : "#/components/schemas/AttachmentRequest" }, "type" : "array" }, "text" : { "type" : "string" } }, "required" : [ "attachments", "text" ], "type" : "object" }, "PreferencesBody" : { "properties" : { "greetingEnabled" : { "type" : "boolean" }, "hintsEnabled" : { "type" : "boolean" } }, "required" : [ "greetingEnabled", "hintsEnabled" ], "type" : "object" }, "PreferencesView" : { "properties" : { "greetingEnabled" : { "type" : "boolean" }, "hintsEnabled" : { "type" : "boolean" } }, "required" : [ "greetingEnabled", "hintsEnabled" ], "type" : "object" }, "Principles" : { "properties" : { "content" : { "type" : "string" }, "overridden" : { "type" : "boolean" } }, "required" : [ "content", "overridden" ], "type" : "object" }, "ProfileView" : { "properties" : { "displayName" : { "type" : "string" }, "home" : { "$ref" : "#/components/schemas/HomeLocationView" } }, "required" : [ "displayName" ], "type" : "object" }, "PromoteRequest" : { "properties" : { "name" : { "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "ProposalResponse" : { "properties" : { "id" : { "type" : "string" }, "source" : { "type" : "string" }, "summary" : { "type" : "string" } }, "required" : [ "id", "source", "summary" ], "type" : "object" }, "QosSpec" : { "properties" : { "fallbacks" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "priority" : { "enum" : [ "interactive", "business", "background" ], "type" : "string" } }, "required" : [ "fallbacks", "priority" ], "type" : "object" }, "QuietHoursConfig" : { "properties" : { "enabled" : { "type" : "boolean" }, "end" : { "type" : "string" }, "start" : { "type" : "string" } }, "required" : [ "enabled", "end", "start" ], "type" : "object" }, "RealmLogEntry" : { "properties" : { "dispatchId" : { "type" : "string" }, "level" : { "type" : "string" }, "message" : { "type" : "string" }, "realm" : { "type" : "string" }, "timestamp" : { "format" : "int64", "type" : "integer" } }, "required" : [ "level", "message", "timestamp" ], "type" : "object" }, "RealmLogTail" : { "properties" : { "bufferSize" : { "format" : "int32", "type" : "integer" }, "captureEnabled" : { "type" : "boolean" }, "entries" : { "items" : { "$ref" : "#/components/schemas/RealmLogEntry" }, "type" : "array" }, "filteredOut" : { "type" : "boolean" } }, "required" : [ "bufferSize", "captureEnabled", "entries", "filteredOut" ], "type" : "object" }, "RealmRuntimeSnapshot" : { "properties" : { "build" : { "$ref" : "#/components/schemas/BuildSnapshot" }, "dispatch" : { "$ref" : "#/components/schemas/DispatchSnapshot" }, "jvm" : { "$ref" : "#/components/schemas/JvmSnapshot" } }, "required" : [ "build", "dispatch", "jvm" ], "type" : "object" }, "Receipt" : { "properties" : { "agent" : { "type" : "string" }, "agentVersion" : { "format" : "int32", "type" : "integer" }, "at" : { "format" : "date-time", "type" : "string" }, "decidedBy" : { "type" : "string" }, "decision" : { "type" : "string" }, "entityKeys" : { "items" : { "type" : "string" }, "type" : "array" }, "hash" : { "type" : "string" }, "id" : { "type" : "string" }, "inputHash" : { "type" : "string" }, "ownerId" : { "type" : "string" }, "previousHash" : { "type" : "string" }, "reason" : { "type" : "string" }, "requestId" : { "type" : "string" }, "rule" : { "type" : "string" }, "runId" : { "type" : "string" }, "seq" : { "format" : "int64", "type" : "integer" }, "verb" : { "type" : "string" }, "work" : { "type" : "string" } }, "required" : [ "at", "decision", "entityKeys", "hash", "id", "inputHash", "ownerId", "previousHash", "reason", "rule", "seq", "verb", "work" ], "type" : "object" }, "RememberFactRequest" : { "properties" : { "confidence" : { "format" : "double", "type" : "number" }, "text" : { "type" : "string" } }, "required" : [ "text" ], "type" : "object" }, "RequestMessage" : { "properties" : { "content" : { }, "role" : { "type" : "string" } }, "required" : [ "role" ], "type" : "object" }, "ResolvedModel" : { "properties" : { "local" : { "type" : "boolean" }, "name" : { "type" : "string" }, "provider" : { "type" : "string" } }, "required" : [ "local", "name" ], "type" : "object" }, "RetireRequest" : { "properties" : { "reason" : { "type" : "string" } }, "required" : [ "reason" ], "type" : "object" }, "Retired" : { "properties" : { "agent" : { "type" : "string" }, "keysRevoked" : { "format" : "int32", "type" : "integer" }, "slotsDeleted" : { "format" : "int32", "type" : "integer" } }, "required" : [ "agent", "keysRevoked", "slotsDeleted" ], "type" : "object" }, "RoleModelRequest" : { "properties" : { "model" : { "description" : "The model the role uses in this world; blank for the deployment's choice", "type" : "string" } }, "type" : "object" }, "RoleView" : { "properties" : { "custom" : { "type" : "boolean" }, "deploymentModel" : { "type" : "string" }, "description" : { "type" : "string" }, "group" : { "type" : "string" }, "id" : { "type" : "string" }, "resolved" : { "$ref" : "#/components/schemas/ResolvedModel" }, "usedBy" : { "items" : { "type" : "string" }, "type" : "array" }, "worldModel" : { "type" : "string" } }, "required" : [ "custom", "id", "usedBy" ], "type" : "object" }, "RouterView" : { "properties" : { "contexts" : { "items" : { "$ref" : "#/components/schemas/ContextView" }, "type" : "array" }, "deploymentUses" : { "items" : { "$ref" : "#/components/schemas/DeploymentUse" }, "type" : "array" }, "models" : { "items" : { "$ref" : "#/components/schemas/ResolvedModel" }, "type" : "array" }, "roles" : { "items" : { "$ref" : "#/components/schemas/RoleView" }, "type" : "array" } }, "required" : [ "contexts", "deploymentUses", "models", "roles" ], "type" : "object" }, "RoutineRef" : { "properties" : { "action" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" } }, "required" : [ "action" ], "type" : "object" }, "RoutineView" : { "properties" : { "description" : { "type" : "string" }, "firing" : { "enum" : [ "off", "observing", "on" ], "type" : "string" }, "missing" : { "type" : "boolean" }, "name" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" }, "trigger" : { "type" : "string" } }, "required" : [ "description", "firing", "missing", "name", "stage", "trigger" ], "type" : "object" }, "RunDetail" : { "properties" : { "receipts" : { "items" : { "$ref" : "#/components/schemas/Receipt" }, "type" : "array" }, "run" : { "$ref" : "#/components/schemas/AgentRun" } }, "required" : [ "receipts", "run" ], "type" : "object" }, "RunNowRequest" : { "properties" : { "job" : { "type" : "string" } }, "required" : [ "job" ], "type" : "object" }, "RunSavedRequest" : { "properties" : { "args" : { "additionalProperties" : { }, "type" : "object" } }, "required" : [ "args" ], "type" : "object" }, "RunWatchRequest" : { "properties" : { "idempotencyKey" : { "type" : "string" } }, "type" : "object" }, "SampleDataExportResponse" : { "properties" : { "edges" : { "items" : { "$ref" : "#/components/schemas/EdgeRequest" }, "type" : "array" }, "matched" : { "format" : "int32", "type" : "integer" }, "name" : { "type" : "string" }, "nodes" : { "items" : { "$ref" : "#/components/schemas/NodeRequest" }, "type" : "array" }, "realm" : { "type" : "string" }, "truncated" : { "type" : "boolean" } }, "required" : [ "edges", "matched", "name", "nodes", "realm", "truncated" ], "type" : "object" }, "SampleSetRequest" : { "properties" : { "edges" : { "items" : { "$ref" : "#/components/schemas/EdgeRequest" }, "type" : "array" }, "matched" : { "format" : "int32", "type" : "integer" }, "name" : { "type" : "string" }, "nodes" : { "items" : { "$ref" : "#/components/schemas/NodeRequest" }, "type" : "array" }, "realm" : { "type" : "string" }, "truncated" : { "type" : "boolean" } }, "required" : [ "edges", "name", "nodes", "realm" ], "type" : "object" }, "SamplingSpec" : { "properties" : { "maxTokens" : { "format" : "int32", "type" : "integer" }, "temperature" : { "items" : { "format" : "double", "type" : "number" }, "type" : "array" } }, "type" : "object" }, "SearchMemoryRequest" : { "description" : "A memory search", "properties" : { "minConfidence" : { "default" : "0.5", "description" : "Minimum similarity to include, 0..1", "format" : "double", "type" : "number" }, "query" : { "description" : "The text to match against the user's memories", "type" : "string" }, "topK" : { "default" : "20", "description" : "How many results to return; clamped to 1..30", "format" : "int32", "type" : "integer" } }, "required" : [ "query" ], "type" : "object" }, "SecretValue" : { "properties" : { "value" : { "type" : "string" } }, "required" : [ "value" ], "type" : "object" }, "SectionHeadingView" : { "properties" : { "depth" : { "format" : "int32", "type" : "integer" }, "hasText" : { "type" : "boolean" }, "id" : { "type" : "string" }, "leaf" : { "type" : "boolean" }, "ordinal" : { "format" : "int64", "type" : "integer" }, "parentId" : { "type" : "string" }, "title" : { "type" : "string" } }, "required" : [ "hasText", "id", "leaf", "title" ], "type" : "object" }, "Sender" : { "properties" : { "kind" : { "enum" : [ "PERSON", "AGENT", "APPLIANCE" ], "type" : "string" }, "name" : { "type" : "string" } }, "required" : [ "kind", "name" ], "type" : "object" }, "SensorBatchRequest" : { "properties" : { "events" : { "items" : { "oneOf" : [ { "$ref" : "#/components/schemas/Context" }, { "$ref" : "#/components/schemas/Fact" } ] }, "type" : "array" }, "source" : { "type" : "string" }, "timeZone" : { "type" : "string" } }, "required" : [ "events", "source" ], "type" : "object" }, "SensorBatchResponse" : { "properties" : { "duplicates" : { "format" : "int32", "type" : "integer" }, "observed" : { "format" : "int32", "type" : "integer" }, "receipts" : { "items" : { "$ref" : "#/components/schemas/EventReceipt" }, "type" : "array" }, "rejected" : { "format" : "int32", "type" : "integer" }, "stored" : { "format" : "int32", "type" : "integer" } }, "required" : [ "duplicates", "observed", "receipts", "rejected", "stored" ], "type" : "object" }, "SensorCommand" : { "properties" : { "id" : { "type" : "string" }, "kind" : { "type" : "string" }, "payload" : { "additionalProperties" : { }, "type" : "object" } }, "required" : [ "id", "kind", "payload" ], "type" : "object" }, "SensorEvent" : { "discriminator" : { "propertyName" : "kind" }, "properties" : { "kind" : { "type" : "string" } }, "required" : [ "kind" ], "type" : "object" }, "SessionSummaryResponse" : { "properties" : { "createdAt" : { "type" : "string" }, "lastActivityAt" : { "type" : "string" }, "sessionId" : { "type" : "string" }, "title" : { "type" : "string" } }, "required" : [ "createdAt", "lastActivityAt", "sessionId" ], "type" : "object" }, "SetContextBody" : { "properties" : { "name" : { "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "SetStageRequest" : { "properties" : { "routine" : { "type" : "string" }, "stage" : { "enum" : [ "off", "observing", "on" ], "type" : "string" } }, "required" : [ "stage" ], "type" : "object" }, "SignalTypeInfo" : { "properties" : { "count" : { "format" : "int64", "type" : "integer" }, "fields" : { "items" : { "type" : "string" }, "type" : "array" }, "lastSeen" : { "type" : "string" }, "typeName" : { "type" : "string" } }, "required" : [ "count", "fields", "lastSeen", "typeName" ], "type" : "object" }, "SkillSummary" : { "properties" : { "description" : { "type" : "string" }, "name" : { "type" : "string" } }, "required" : [ "description", "name" ], "type" : "object" }, "SkipRequest" : { "properties" : { "job" : { "type" : "string" }, "reason" : { "type" : "string" }, "until" : { "format" : "date-time", "type" : "string" } }, "required" : [ "job", "reason" ], "type" : "object" }, "Slots" : { "properties" : { "agent" : { "type" : "string" }, "secrets" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "agent", "secrets" ], "type" : "object" }, "Source" : { "properties" : { "cited" : { "type" : "boolean" }, "dates" : { "$ref" : "#/components/schemas/SourceDates" }, "n" : { "format" : "int32", "type" : "integer" }, "passages" : { "items" : { "type" : "string" }, "type" : "array" }, "score" : { "format" : "double", "type" : "number" }, "sectionId" : { "type" : "string" }, "title" : { "type" : "string" }, "uri" : { "type" : "string" } }, "required" : [ "cited", "dates", "n", "passages", "score" ], "type" : "object" }, "SourceConnection" : { "properties" : { "fields" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "hasSecret" : { "type" : "boolean" }, "kind" : { "type" : "string" }, "variant" : { "type" : "string" } }, "required" : [ "fields", "hasSecret", "kind" ], "type" : "object" }, "SourceDates" : { "properties" : { "createdAt" : { "type" : "string" }, "ingestedAt" : { "type" : "string" }, "modifiedAt" : { "type" : "string" } }, "type" : "object" }, "SourceWire" : { "properties" : { "asserts" : { "type" : "string" }, "confirmation" : { "type" : "string" }, "connected" : { "type" : "boolean" }, "evidence" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "inferred" : { "type" : "string" }, "installedRealm" : { "type" : "string" }, "kind" : { "type" : "string" }, "label" : { "type" : "string" }, "learnable" : { "type" : "boolean" }, "name" : { "type" : "string" }, "neededBy" : { "items" : { "type" : "string" }, "type" : "array" }, "pendingReview" : { "type" : "string" }, "promotedRealms" : { "items" : { "type" : "string" }, "type" : "array" }, "reachable" : { "type" : "boolean" }, "summary" : { "type" : "string" } }, "required" : [ "asserts", "confirmation", "connected", "evidence", "inferred", "kind", "label", "learnable", "name", "neededBy", "promotedRealms", "reachable", "summary" ], "type" : "object" }, "SourcesResponse" : { "properties" : { "sources" : { "items" : { "$ref" : "#/components/schemas/SourceWire" }, "type" : "array" } }, "required" : [ "sources" ], "type" : "object" }, "SseEmitter" : { "properties" : { "timeout" : { "format" : "int64", "type" : "integer" } }, "type" : "object" }, "StageResponse" : { "properties" : { "agent" : { "$ref" : "#/components/schemas/AgentView" }, "refused" : { "type" : "string" } }, "type" : "object" }, "StartFillRequest" : { "properties" : { "budgetPerTick" : { "format" : "int32", "type" : "integer" }, "cypher" : { "type" : "string" }, "label" : { "type" : "string" } }, "required" : [ "budgetPerTick", "cypher", "label" ], "type" : "object" }, "SuggestionResponse" : { "properties" : { "refused" : { "type" : "string" }, "suggestion" : { "$ref" : "#/components/schemas/AgentSuggestion" } }, "type" : "object" }, "SurfaceDictionary" : { "properties" : { "fields" : { "items" : { "type" : "string" }, "type" : "array" }, "panels" : { "additionalProperties" : { "$ref" : "#/components/schemas/SurfacePanel" }, "type" : "object" }, "surface" : { "type" : "string" }, "version" : { "format" : "int32", "type" : "integer" } }, "required" : [ "fields", "panels", "surface", "version" ], "type" : "object" }, "SurfacePanel" : { "properties" : { "controls" : { "items" : { "type" : "string" }, "type" : "array" }, "fields" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "controls", "fields" ], "type" : "object" }, "SurfaceResponse" : { "description" : "The surface recorded, and the fields the assistant will now offer to fill", "properties" : { "fields" : { "description" : "Field names the assistant may now fill", "items" : { "type" : "string" }, "type" : "array" }, "surface" : { "description" : "The surface recorded", "type" : "string" } }, "required" : [ "fields", "surface" ], "type" : "object" }, "SystemStatus" : { "description" : "Memory, CPU, the document ingest queue, document conversion, and embedding coverage, read now", "properties" : { "conversion" : { "$ref" : "#/components/schemas/ConversionStatus" }, "cpu" : { "$ref" : "#/components/schemas/CpuStatus" }, "embeddings" : { "$ref" : "#/components/schemas/EmbeddingsStatus" }, "ingest" : { "$ref" : "#/components/schemas/IngestStatus" }, "memory" : { "$ref" : "#/components/schemas/MemoryStatus" } }, "required" : [ "conversion", "cpu", "embeddings", "ingest", "memory" ], "type" : "object" }, "TagsRequest" : { "properties" : { "tags" : { "items" : { "type" : "string" }, "type" : "array" }, "uri" : { "type" : "string" } }, "required" : [ "tags", "uri" ], "type" : "object" }, "TagsResponse" : { "properties" : { "status" : { "type" : "string" }, "tags" : { "items" : { "type" : "string" }, "type" : "array" }, "uri" : { "type" : "string" } }, "required" : [ "status", "tags", "uri" ], "type" : "object" }, "TextIngestRequest" : { "properties" : { "content" : { "type" : "string" }, "name" : { "type" : "string" }, "tags" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "content", "name" ], "type" : "object" }, "Thread" : { "properties" : { "createdAt" : { "format" : "date-time", "type" : "string" }, "id" : { "type" : "string" }, "ownerId" : { "type" : "string" }, "title" : { "type" : "string" }, "updatedAt" : { "format" : "date-time", "type" : "string" } }, "required" : [ "createdAt", "id", "ownerId", "title", "updatedAt" ], "type" : "object" }, "ThreadList" : { "properties" : { "threads" : { "items" : { "$ref" : "#/components/schemas/Thread" }, "type" : "array" } }, "required" : [ "threads" ], "type" : "object" }, "ThreadMessage" : { "properties" : { "attachments" : { "items" : { "$ref" : "#/components/schemas/Attachment" }, "type" : "array" }, "createdAt" : { "format" : "date-time", "type" : "string" }, "from" : { "$ref" : "#/components/schemas/Sender" }, "id" : { "type" : "string" }, "inReplyTo" : { "type" : "string" }, "mentions" : { "items" : { "type" : "string" }, "type" : "array" }, "text" : { "type" : "string" }, "threadId" : { "type" : "string" }, "wordsOnly" : { "type" : "boolean" } }, "required" : [ "attachments", "createdAt", "from", "id", "mentions", "text", "threadId", "wordsOnly" ], "type" : "object" }, "ThreadsResponse" : { "properties" : { "error" : { "type" : "string" }, "threads" : { "items" : { "$ref" : "#/components/schemas/EmailThread" }, "type" : "array" } }, "required" : [ "threads" ], "type" : "object" }, "TimeoutsConfig" : { "properties" : { "kgQuerySeconds" : { "format" : "int64", "type" : "integer" }, "scriptSeconds" : { "format" : "int64", "type" : "integer" } }, "type" : "object" }, "TimerSummary" : { "properties" : { "count" : { "format" : "int64", "type" : "integer" }, "maxMillis" : { "format" : "double", "type" : "number" }, "outcome" : { "type" : "string" }, "totalMillis" : { "format" : "double", "type" : "number" } }, "required" : [ "count", "maxMillis", "outcome", "totalMillis" ], "type" : "object" }, "TipSchedule" : { "properties" : { "frequency" : { "enum" : [ "NEVER", "DAILY", "WEEKDAYS", "WEEKLY" ], "type" : "string" }, "hour" : { "format" : "int32", "type" : "integer" } }, "required" : [ "frequency", "hour" ], "type" : "object" }, "TipScheduleView" : { "properties" : { "cron" : { "type" : "string" }, "frequency" : { "enum" : [ "NEVER", "DAILY", "WEEKDAYS", "WEEKLY" ], "type" : "string" }, "hour" : { "format" : "int32", "type" : "integer" } }, "required" : [ "frequency", "hour" ], "type" : "object" }, "TourDeletedResponse" : { "description" : "Whether a saved tour was removed", "properties" : { "deleted" : { "type" : "boolean" } }, "required" : [ "deleted" ], "type" : "object" }, "TourImportRequest" : { "description" : "A tour file to store", "properties" : { "yaml" : { "description" : "The tour's YAML, as exported or as a realm would ship it", "type" : "string" } }, "required" : [ "yaml" ], "type" : "object" }, "TourListResponse" : { "description" : "Every tour declared for a world", "properties" : { "tours" : { "items" : { "$ref" : "#/components/schemas/TourSummary" }, "type" : "array" } }, "required" : [ "tours" ], "type" : "object" }, "TourRefusal" : { "description" : "Why a tour was refused, in the server's own words", "properties" : { "error" : { "description" : "The refusal, as a sentence to show the user", "type" : "string" } }, "required" : [ "error" ], "type" : "object" }, "TourStepStatusRequest" : { "description" : "The parameters a tour has collected so far, bound into the step's precondition", "properties" : { "params" : { "additionalProperties" : { }, "type" : "object" } }, "required" : [ "params" ], "type" : "object" }, "TourStepStatusResponse" : { "description" : "Whether a step's precondition is already satisfied", "properties" : { "detail" : { "description" : "Why, when the status is UNKNOWN — the query error in the author's words", "type" : "string" }, "status" : { "enum" : [ "DONE", "TODO", "UNKNOWN" ], "type" : "string" } }, "required" : [ "status" ], "type" : "object" }, "TourStepView" : { "description" : "One step, as its file declared it — minus the precondition, which stays server-side", "properties" : { "presentation" : { "additionalProperties" : { }, "type" : "object" }, "watchable" : { "description" : "This step HAS a precondition, without saying what it is. A client that hands a step to the user can then poll for it and carry on by itself when the world says the user has done the thing — go and connect a coding agent, and the tour notices. Without this flag a client would have to poll every hand-over blindly, spending a query every few seconds on steps that can never come true.", "type" : "boolean" } }, "required" : [ "presentation", "watchable" ], "type" : "object" }, "TourSummary" : { "description" : "A tour: its identity, its provenance, and the client's own declarations", "properties" : { "declaredId" : { "description" : "What the tour's own file called it — the id that survives an export", "type" : "string" }, "deletable" : { "description" : "This world can remove it. NOT the same as userSaved: a tour hand-written into a user's own config is theirs but is not this server's to delete, so a client offering Delete for it would offer a button that silently does nothing.", "type" : "boolean" }, "id" : { "description" : "Unique within this world, and what every other call addresses", "type" : "string" }, "presentation" : { "additionalProperties" : { }, "description" : "Everything the tour's YAML declared beyond id and steps, uninterpreted", "type" : "object" }, "source" : { "description" : "The realm that shipped it, or absent for a world's own and a user's own. Carried rather than derived from the id — a namespace prefix is not something a client can reliably strip.", "type" : "string" }, "steps" : { "items" : { "$ref" : "#/components/schemas/TourStepView" }, "type" : "array" }, "userSaved" : { "description" : "Imported or recorded by this user, rather than shipped by a realm or the world", "type" : "boolean" } }, "required" : [ "declaredId", "deletable", "id", "presentation", "steps", "userSaved" ], "type" : "object" }, "TransitionRule" : { "properties" : { "crossesAbove" : { "format" : "double", "type" : "number" }, "crossesBelow" : { "format" : "double", "type" : "number" }, "field" : { "type" : "string" }, "from" : { "$ref" : "#/components/schemas/JsonNode" }, "name" : { "type" : "string" }, "to" : { "$ref" : "#/components/schemas/JsonNode" } }, "required" : [ "field", "name" ], "type" : "object" }, "Upcoming" : { "properties" : { "agent" : { "type" : "string" }, "counts" : { "$ref" : "#/components/schemas/Counts" }, "expected" : { "items" : { "$ref" : "#/components/schemas/Expected" }, "type" : "array" }, "firings" : { "items" : { "$ref" : "#/components/schemas/Firing" }, "type" : "array" }, "inFlight" : { "items" : { "$ref" : "#/components/schemas/InFlight" }, "type" : "array" }, "onSignals" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "agent", "counts", "expected", "firings", "inFlight", "onSignals" ], "type" : "object" }, "UpcomingResponse" : { "properties" : { "refused" : { "type" : "string" }, "upcoming" : { "$ref" : "#/components/schemas/Upcoming" } }, "type" : "object" }, "UpdateActionRequest" : { "properties" : { "description" : { "type" : "string" }, "inputTypeNames" : { "items" : { "type" : "string" }, "type" : "array", "uniqueItems" : true }, "llmModel" : { "type" : "string" }, "llmTemperature" : { "format" : "double", "type" : "number" }, "outputTypeName" : { "type" : "string" }, "prompt" : { "type" : "string" }, "references" : { "items" : { "type" : "string" }, "type" : "array" }, "tools" : { "items" : { "type" : "string" }, "type" : "array" } }, "type" : "object" }, "UpdatePersonalityRequest" : { "properties" : { "files" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } }, "required" : [ "files" ], "type" : "object" }, "UpdateRequest" : { "properties" : { "content" : { "type" : "string" } }, "required" : [ "content" ], "type" : "object" }, "UpdateWatchRequest" : { "properties" : { "clearCron" : { "type" : "boolean" }, "clearDelivery" : { "type" : "boolean" }, "cron" : { "type" : "string" }, "delivery" : { "$ref" : "#/components/schemas/DeliverySpec" }, "diffSpec" : { "$ref" : "#/components/schemas/DiffSpec" }, "enabled" : { "type" : "boolean" }, "firstRunPolicy" : { "enum" : [ "ESTABLISH_BASELINE", "EMIT_CURRENT" ], "type" : "string" }, "name" : { "type" : "string" }, "params" : { "additionalProperties" : { }, "type" : "object" } }, "required" : [ "clearCron", "clearDelivery" ], "type" : "object" }, "UrlIngestRequest" : { "properties" : { "fromOrgDomain" : { "type" : "string" }, "tags" : { "items" : { "type" : "string" }, "type" : "array" }, "url" : { "type" : "string" } }, "required" : [ "url" ], "type" : "object" }, "UserContextView" : { "properties" : { "contexts" : { "items" : { "type" : "string" }, "type" : "array" }, "current" : { "type" : "string" } }, "required" : [ "contexts", "current" ], "type" : "object" }, "VerbSpec" : { "properties" : { "args" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "description" : { "type" : "string" }, "group" : { "type" : "string" }, "name" : { "type" : "string" } }, "required" : [ "args", "description", "group", "name" ], "type" : "object" }, "Verification" : { "properties" : { "brokenAt" : { "format" : "int64", "type" : "integer" }, "intact" : { "type" : "boolean" }, "receipts" : { "format" : "int32", "type" : "integer" }, "why" : { "type" : "string" } }, "required" : [ "intact", "receipts" ], "type" : "object" }, "View" : { "properties" : { "messages" : { "items" : { "$ref" : "#/components/schemas/ThreadMessage" }, "type" : "array" }, "thread" : { "$ref" : "#/components/schemas/Thread" }, "waitingOn" : { "items" : { "type" : "string" }, "type" : "array" } }, "required" : [ "messages", "thread", "waitingOn" ], "type" : "object" }, "ViewDebugInfo" : { "properties" : { "cachedMembers" : { "format" : "int64", "type" : "integer" }, "cypher" : { "type" : "string" }, "dataContract" : { "$ref" : "#/components/schemas/DataContractBindingSpec" }, "description" : { "type" : "string" }, "expiresAt" : { "format" : "int64", "type" : "integer" }, "materialized" : { "type" : "boolean" }, "name" : { "type" : "string" }, "outputLabel" : { "type" : "string" }, "params" : { "additionalProperties" : { "$ref" : "#/components/schemas/ViewParamSpec" }, "type" : "object" }, "source" : { "type" : "string" }, "ttl" : { "type" : "string" } }, "required" : [ "cypher", "description", "materialized", "name", "params" ], "type" : "object" }, "ViewParamSpec" : { "properties" : { "choices" : { "description" : "The fixed set of values this param accepts — rendered as a select, enforced at invocation. Absent = any value of the declared type.", "items" : { }, "type" : "array" }, "default" : { "description" : "Used when an invocation omits this param. Absent = required on invocation." }, "description" : { "description" : "What the argument means — rendered verbatim as the field's hint.", "type" : "string" }, "required" : { "type" : "boolean" }, "type" : { "default" : "string", "description" : "The coercion applied to supplied values, and the form control a UI renders (int/number a number field, boolean a checkbox, date a date picker). float and double are aliases of number.", "enum" : [ "string", "int", "number", "float", "double", "boolean", "date" ], "type" : "string" } }, "type" : "object" }, "VoiceOptionView" : { "properties" : { "id" : { "type" : "string" }, "label" : { "type" : "string" } }, "required" : [ "id", "label" ], "type" : "object" }, "VoiceProfileView" : { "properties" : { "available" : { "type" : "boolean" }, "effects" : { "items" : { "type" : "string" }, "type" : "array" }, "selectedEffects" : { "items" : { "type" : "string" }, "type" : "array" }, "voiceName" : { "type" : "string" }, "voices" : { "items" : { "$ref" : "#/components/schemas/VoiceOptionView" }, "type" : "array" } }, "required" : [ "available", "effects", "selectedEffects", "voices" ], "type" : "object" }, "VoiceSessionView" : { "properties" : { "effects" : { "items" : { "type" : "string" }, "type" : "array" }, "replacements" : { "items" : { "type" : "string" }, "type" : "array" }, "speed" : { "format" : "double", "type" : "number" }, "token" : { "type" : "string" }, "transcriber" : { "type" : "string" }, "voice" : { "type" : "string" } }, "required" : [ "effects", "replacements", "speed", "token", "transcriber", "voice" ], "type" : "object" }, "VoiceUpdateBody" : { "properties" : { "effects" : { "items" : { "type" : "string" }, "type" : "array" }, "voiceName" : { "type" : "string" } }, "required" : [ "effects" ], "type" : "object" }, "WebFetchConfig" : { "properties" : { "crawler" : { "type" : "string" }, "retriever" : { "type" : "string" } }, "type" : "object" }, "WorldConfig" : { "properties" : { "actionCompilerLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "activePersonality" : { "type" : "string" }, "apiExplorerLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "chat" : { "$ref" : "#/components/schemas/LlmConfig" }, "codingLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "collectorConfig" : { "$ref" : "#/components/schemas/CollectorConfig" }, "fallbackCodingLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "filesTrustedRoots" : { "items" : { "type" : "string" }, "type" : "array" }, "lensLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "llmRoles" : { "additionalProperties" : { "$ref" : "#/components/schemas/LlmConfig" }, "type" : "object" }, "mcpMode" : { "enum" : [ "ASSISTANT", "DEVELOPER" ], "type" : "string" }, "memoryLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "notificationRouting" : { "$ref" : "#/components/schemas/NotificationRoutingConfig" }, "plannerLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "rankerLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "sandboxDockerimage" : { "type" : "string" }, "timeouts" : { "$ref" : "#/components/schemas/TimeoutsConfig" }, "toolRouterLlm" : { "$ref" : "#/components/schemas/LlmConfig" }, "version" : { "format" : "int32", "type" : "integer" }, "webFetch" : { "$ref" : "#/components/schemas/WebFetchConfig" } }, "required" : [ "activePersonality", "filesTrustedRoots", "llmRoles", "version" ], "type" : "object" } }, "securitySchemes" : { "apiKeyAuth" : { "description" : "An API key minted in the console under Settings → API keys. Also accepted as `Authorization: Bearer `.", "in" : "header", "name" : "X-Embabel-Api-Key", "type" : "apiKey" }, "basicAuth" : { "description" : "The appliance's own user accounts. The Worlds console proxies these on the same origin.", "scheme" : "basic", "type" : "http" } } }, "info" : { "contact" : { "name" : "Embabel", "url" : "https://embabel.com" }, "description" : "REST API for the Embabel Me assistant platform.", "title" : "Embabel Me", "version" : "0.2.0-SNAPSHOT" }, "openapi" : "3.1.0", "paths" : { "/api/v1/about" : { "get" : { "description" : "The server's commit and the versions of its libraries.", "operationId" : "about", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/AboutResponse" } } }, "description" : "Components, server first" } }, "summary" : "Component versions", "tags" : [ "About" ] } }, "/api/v1/actions" : { "get" : { "description" : "Returns every action the planner knows about, with its input/output types and whether it can be deleted from here. 'deletable' is true only for actions whose YAML lives directly under this world's config/actions directory — realm-shipped and platform-defined actions report false.", "operationId" : "listActions_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/ActionListItem" }, "type" : "array" } } }, "description" : "List of actions" } }, "summary" : "List actions in full", "tags" : [ "Actions" ] } }, "/api/v1/actions/available-references" : { "get" : { "operationId" : "availableReferences", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List references available for action compilation (skills, RAG docs, memory)", "tags" : [ "Actions" ] } }, "/api/v1/actions/available-tools" : { "get" : { "operationId" : "availableTools", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List tools available for action compilation", "tags" : [ "Actions" ] } }, "/api/v1/actions/available-types" : { "get" : { "description" : "The built-in types plus the world's dynamic types.", "operationId" : "availableTypes", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "type" : "string" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List types available as action inputs/outputs", "tags" : [ "Actions" ] } }, "/api/v1/actions/compile" : { "post" : { "description" : "Compiles a natural language description into a PromptedActionSpec. Uses the AI to generate a Jinja2 prompt template and saves to the world's config/actions directory. The output type defaults to BackgroundMessage when not specified.", "operationId" : "compile", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CompileRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Compilation result" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Compilation failed" } }, "summary" : "Compile an action", "tags" : [ "Actions" ] } }, "/api/v1/actions/spec/{name}" : { "delete" : { "description" : "Deletes an action spec from the world's config/actions directory, along with any sibling TypeScript file of the same name. Realm-shipped and platform actions cannot be deleted.", "operationId" : "deleteAction", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action deleted" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action cannot be deleted" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action not found" } }, "summary" : "Delete an action", "tags" : [ "Actions" ] }, "get" : { "description" : "Returns the full spec for a world action. Only PromptedActionSpecs in the world (not realms) include editable fields.", "operationId" : "getAction", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Action spec" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Action not found" } }, "summary" : "Get action details", "tags" : [ "Actions" ] }, "post" : { "description" : "Updates a PromptedActionSpec in the world. Only actions in the world's config/actions directory (not realm-shipped ones) can be edited.", "operationId" : "updateAction", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateActionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action updated" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action is not editable" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action not found" } }, "summary" : "Update an action", "tags" : [ "Actions" ] } }, "/api/v1/activity" : { "get" : { "description" : "Running first, then recently settled, newest first. Settled work is kept briefly because \"did that work?\" is asked immediately after the thing finishes — dropping it on completion would make a fast success look like one that never ran.", "operationId" : "activity", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/ActivityRow" }, "type" : "array" } } }, "description" : "Pinned failures first, then activity, running first" } }, "summary" : "Work in progress, and work that just finished", "tags" : [ "Activity" ] } }, "/api/v1/activity/pins/dismiss" : { "post" : { "operationId" : "dismissPin", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DismissPinBody" } } }, "required" : true }, "responses" : { "204" : { "description" : "Dismissed, or there was nothing pinned by that label" } }, "summary" : "Dismiss a pinned failure", "tags" : [ "Activity" ] } }, "/api/v1/activity/stats" : { "get" : { "description" : "Per job: runs counted, failures among them, median, 95th percentile and longest duration, slowest tail first. Over each job's most recent runs since the app started; `since` is when the oldest run counted began, null when nothing has run.", "operationId" : "stats", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ActivityStats" } } }, "description" : "Per-job durations, slowest tail first" } }, "summary" : "How long each job takes", "tags" : [ "Activity" ] } }, "/api/v1/admin/catchup/run" : { "post" : { "operationId" : "run_5", "parameters" : [ { "description" : "Username to run catchup for.", "in" : "query", "name" : "username", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Run report: signal and notification counts and duration" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown user" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Catchup run failed" } }, "summary" : "Run catchup now for a user (refreshes meeting-prep notes)", "tags" : [ "Catchup" ] } }, "/api/v1/admin/code-action/catalog" : { "get" : { "operationId" : "catalog", "parameters" : [ { "in" : "query", "name" : "username", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown username" } }, "summary" : "List every realm API operation available to a user, classified read-only vs write", "tags" : [ "Code Actions" ] } }, "/api/v1/admin/code-action/respond" : { "post" : { "operationId" : "respond", "parameters" : [ { "in" : "query", "name" : "processId", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "accepted", "required" : false, "schema" : { "default" : true, "type" : "boolean" } } ], "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown or expired process, or process not awaiting confirmation" } }, "summary" : "Approve or reject a write parked at a confirmation gate, by process id", "tags" : [ "Code Actions" ] } }, "/api/v1/admin/code-action/run" : { "post" : { "operationId" : "run_4", "parameters" : [ { "in" : "query", "name" : "username", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "goal", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "question", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "seed", "required" : false, "schema" : { "default" : "run", "type" : "string" } }, { "in" : "query", "name" : "dryRun", "required" : false, "schema" : { "default" : false, "type" : "boolean" } } ], "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown username, or neither goal nor question given" } }, "summary" : "Plan and run (or dry-run) a code-action goal or natural-language question for a user", "tags" : [ "Code Actions" ] } }, "/api/v1/admin/enrichment/run" : { "post" : { "operationId" : "run_3", "parameters" : [ { "in" : "query", "name" : "username", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown username" } }, "summary" : "Run persisted virtual-join enrichment for a user now, synchronously", "tags" : [ "Enrichment" ] } }, "/api/v1/admin/handlers/delete" : { "post" : { "operationId" : "delete_1", "parameters" : [ { "in" : "query", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerMutationResponse" } } }, "description" : "Whether it was deleted, and the server's own sentence about it" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Delete a user-authored handler (realm handlers can only be disabled)", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/dry-run" : { "post" : { "operationId" : "dryRun_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerDryRunRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerDryRunResponse" } } }, "description" : "What the run saw, logged, and how it ended" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Run a TypeScript handler observe-only against a sample or the most recent matching signal", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/generate" : { "post" : { "operationId" : "generate_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerGenerateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerGenerateResponse" } } }, "description" : "The generated source and whether it type-checks" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Generate (or, with `current`, refine) a TypeScript handler from English, with the tsc verdict", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/list" : { "post" : { "operationId" : "list_6", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerListResponse" } } }, "description" : "The user's handlers, and the realm ones they could adopt" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "List the user's handlers plus inactive realm-shipped handlers available to adopt", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/open" : { "post" : { "operationId" : "open", "parameters" : [ { "in" : "query", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerOpenResponse" } } }, "description" : "The handler's source and its triggers" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No such handler" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Return one handler's source and metadata", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/save" : { "post" : { "operationId" : "save", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerSaveRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerMutationResponse" } } }, "description" : "Whether it was persisted, and the server's own sentence about it" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Create or update a handler, gated on TypeScript compilation", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/set-enabled" : { "post" : { "operationId" : "setEnabled_1", "parameters" : [ { "in" : "query", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "enabled", "required" : true, "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerEnabledResponse" } } }, "description" : "The firing state now in force" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Enable (adopt) or disable a handler for this user", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/set-schedule" : { "post" : { "operationId" : "setSchedule", "parameters" : [ { "in" : "query", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "schedule", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerScheduleResponse" } } }, "description" : "The schedule now in force, or null when cleared" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Set or clear a per-user cron schedule for a handler", "tags" : [ "Handlers" ] } }, "/api/v1/admin/handlers/validate" : { "post" : { "operationId" : "validate_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerValidateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerValidateResponse" } } }, "description" : "The tsc verdict, with its errors in source coordinates" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HandlerErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Type-check a handler body without saving or running it", "tags" : [ "Handlers" ] } }, "/api/v1/admin/kg/annotations/dry-run" : { "post" : { "operationId" : "dryRun", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AnnotateDryRunRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAnnotationDryRunResponse" } } }, "description" : "The frozen plan and the diffs it would write" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Annotation writes disabled by feature flag" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Plan rejected, expired, or frozen for another user" } }, "summary" : "Freeze an annotation plan: validate and select matching nodes, writing nothing", "tags" : [ "KG Annotations" ] } }, "/api/v1/admin/kg/annotations/{planId}/apply" : { "post" : { "operationId" : "apply", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "planId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAnnotationOutcomeResponse" } } }, "description" : "The outcome: committed counts and post-images" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Annotation writes disabled by feature flag" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Plan rejected, expired, or frozen for another user" } }, "summary" : "Apply a frozen annotation plan once, returning committed counts and post-images", "tags" : [ "KG Annotations" ] } }, "/api/v1/admin/kg/annotations/{planId}/undo" : { "post" : { "operationId" : "undo", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "planId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAnnotationOutcomeResponse" } } }, "description" : "The outcome: what the undo reverted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Annotation writes disabled by feature flag" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Plan rejected, expired, or frozen for another user" } }, "summary" : "Conditionally undo an applied plan; a later edit wins and reports as a conflict", "tags" : [ "KG Annotations" ] } }, "/api/v1/admin/kg/ask" : { "post" : { "description" : "`scope` names a declared scope (a focus) to answer WITHIN: generation sees only that scope's realms' schema, plus the always-on core. Not a captured query scope. Omitted, the whole world answers — the default, and the pre-scope behaviour.", "operationId" : "ask_1", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The ask scope to use, as `GET /ask/scopes` lists them. Omitted means the whole graph.", "in" : "query", "name" : "scope", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAskRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgQueryResult" } } }, "description" : "The answer, with the cypher that produced it and what it cost" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgUnknownScopeResponse" } } }, "description" : "Unknown scope; the declared names travel with the refusal" } }, "summary" : "Answer a natural-language question by generating and executing scoped Cypher", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/ask/scopes" : { "get" : { "operationId" : "askScopes", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/KgAskScopeInfo" }, "type" : "array" } } }, "description" : "The world's declared scopes; empty when none are declared" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "List the named scopes the acting user's asks can be narrowed to", "tags" : [ "Virtual Cypher" ] }, "post" : { "operationId" : "createAskScope", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgCreateScopeRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAskScopeInfo" } } }, "description" : "The scope as declared; `scope=` accepts it immediately" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgBadRealmsResponse" } } }, "description" : "Bad name grammar, no realms, or realms not installed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "A scope with that name already exists" } }, "summary" : "Create a named scope (a world-tier focus) asks can be narrowed to", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/ask/scopes/{name}" : { "delete" : { "operationId" : "deleteAskScope", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The view's name, as `GET /views` lists it.", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAskScopeInfo" } } }, "description" : "The scope as it was before deletion" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgUnknownScopeResponse" } } }, "description" : "Unknown scope; the declared names travel with the refusal" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "The scope is realm-shipped and is removed with its realm" } }, "summary" : "Delete a world-tier named scope", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/decorate" : { "get" : { "operationId" : "list_10", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDecoratorListResponse" } } }, "description" : "The registered decorators" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "List the registered node decorators and their tick, batch and staleness settings", "tags" : [ "KG Decoration" ] } }, "/api/v1/admin/kg/decorate/{name}" : { "post" : { "operationId" : "runNow", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDecorationReport" } } }, "description" : "What the tick did" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDecorationReport" } } }, "description" : "Unknown decorator" } }, "summary" : "Run one tick of a decorator now over its stale candidates", "tags" : [ "KG Decoration" ] } }, "/api/v1/admin/kg/decorate/{name}/{nodeId}" : { "post" : { "operationId" : "runFor", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "nodeId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDecorationReport" } } }, "description" : "What the forced run did" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDecorationReport" } } }, "description" : "Unknown decorator" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDecorationReport" } } }, "description" : "Decoration failed" } }, "summary" : "Force a decorator to run against one specific node, bypassing the staleness check", "tags" : [ "KG Decoration" ] } }, "/api/v1/admin/kg/derive" : { "post" : { "description" : "The rule set's derived label is visible to the query as an ordinary label; nothing persists. Invalid rule sets are refused with the validator's messages.", "operationId" : "derive", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDeriveRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDeriveResponse" } } }, "description" : "The query result over the derived overlay" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "The rule set failed validation; `error` carries every violation" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Execute Cypher with a caller-supplied DERIVE rule set evaluated for this query only", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/execute" : { "post" : { "description" : "Three modes: background=true returns a run handle immediately and may park awaiting input; waitSeconds=N watches for that long then returns a run handle; with neither, the call is fully synchronous.", "operationId" : "execute", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "Return a run handle immediately instead of waiting, and allow the run to park awaiting input.", "in" : "query", "name" : "background", "required" : false, "schema" : { "default" : false, "type" : "boolean" } }, { "description" : "Watch the run for this many seconds, then return a handle if it has not finished. Omitted with background=false means wait indefinitely.", "in" : "query", "name" : "waitSeconds", "required" : false, "schema" : { "format" : "int64", "type" : "integer" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgExecuteRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KgQueryResult" }, { "$ref" : "#/components/schemas/KgBackgroundHandle" } ] } } }, "description" : "A finished result, or a run handle when `background=true`" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Bad params or args, or captureAs with background/waitSeconds" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Execute verbatim Cypher through the virtual-cypher engine, synchronously, watched, or in the background", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/fills" : { "get" : { "operationId" : "list_5", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/Fill" }, "type" : "array" } } }, "description" : "The acting user's fills" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "The acting user's fills, newest first, with tick and live-call progress", "tags" : [ "KG Fills" ] }, "post" : { "operationId" : "start", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StartFillRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Fill" } } }, "description" : "The fill, as started" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Start a slow, resumable fill of an expensive materialization", "tags" : [ "KG Fills" ] } }, "/api/v1/admin/kg/fills/{id}" : { "delete" : { "operationId" : "cancel", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The cancelled fill's id and its new state" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Cancel a fill — completed chunks stay cached; nothing is rolled back", "tags" : [ "KG Fills" ] } }, "/api/v1/admin/kg/generate" : { "post" : { "operationId" : "generate", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The ask scope to use, as `GET /ask/scopes` lists them. Omitted means the whole graph.", "in" : "query", "name" : "scope", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateResponse" } } }, "description" : "The generated cypher, its verdict, and what the engine will do" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Generation failed" } }, "summary" : "Generate Cypher and an execution explanation for a question, without running it", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/kill/{runId}" : { "post" : { "operationId" : "kill", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The run handle returned by a background or timed-out execution.", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgKillResponse" } } }, "description" : "Whether the kill landed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Cancel an in-flight run by id (owner-guarded)", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/refine" : { "post" : { "operationId" : "refine", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The ask scope to use, as `GET /ask/scopes` lists them. Omitted means the whole graph.", "in" : "query", "name" : "scope", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgRefineRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateResponse" } } }, "description" : "The revised cypher, its verdict, and what the engine will do" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Refinement failed" } }, "summary" : "Revise existing Cypher per an instruction, without running it", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/reproject" : { "post" : { "operationId" : "reproject", "parameters" : [ { "in" : "query", "name" : "username", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 0, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgReprojectResponse" } } }, "description" : "How much was re-projected" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Unknown username" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Re-project a user's stored propositions into graph edges without re-extracting from source", "tags" : [ "KG Reprojection" ] } }, "/api/v1/admin/kg/runs" : { "get" : { "operationId" : "runs_1", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/KgInFlightRun" }, "type" : "array" } } }, "description" : "The acting user's in-flight runs, newest first" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "List the acting user's in-flight virtual-cypher runs", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/runs/{runId}" : { "get" : { "operationId" : "run_7", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The run handle returned by a background or timed-out execution.", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgRunState" } } }, "description" : "The run's state, with its result once settled" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No such run or not yours" } }, "summary" : "Get the state and, once settled, the result of a background run", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/runs/{runId}/answer" : { "post" : { "operationId" : "answer_1", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The run handle returned by a background or timed-out execution.", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAnswerRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAnswerAccepted" } } }, "description" : "The choice was accepted; the run's new state travels back" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgBadChoiceResponse" } } }, "description" : "Unknown choice" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No such run or not yours" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgRunConflictResponse" } } }, "description" : "Run not awaiting input" } }, "summary" : "Answer a run parked awaiting input: proceed, narrow, background or cancel", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/schema" : { "get" : { "operationId" : "schema", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSchemaResponse" } } }, "description" : "The schema snapshot; empty lists and no `refreshedAt` when none exists" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "The acting user's graph schema — labels, properties, relationship triples", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/schema/{label}/{property}/values" : { "get" : { "operationId" : "propertyValues", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The node label to read the property from.", "in" : "path", "name" : "label", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The property name on that label.", "in" : "path", "name" : "property", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgPropertyValuesResponse" } } }, "description" : "The value domain in one of its three states" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "The legal values of a property: the set, or its size when too wide, or why it cannot be enumerated", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/scopes" : { "get" : { "operationId" : "list_9", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgScopeListResponse" } } }, "description" : "The scopes; an expired scope is already absent" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "List the acting user's live captured scopes, newest first", "tags" : [ "KG Scopes" ] } }, "/api/v1/admin/kg/scopes/{name}" : { "delete" : { "operationId" : "delete_4", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgScopeDeleteResponse" } } }, "description" : "Whether anything was deleted — false is an honest no-op, not an error" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Delete a captured scope", "tags" : [ "KG Scopes" ] } }, "/api/v1/admin/kg/scopes/{name}/pin" : { "post" : { "operationId" : "pin", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgScopeInfo" } } }, "description" : "The scope as stored, now with no expiry" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No such scope (or it already expired)" } }, "summary" : "Pin a captured scope: clear its expiry so it survives until explicitly deleted", "tags" : [ "KG Scopes" ] } }, "/api/v1/admin/kg/validate" : { "post" : { "operationId" : "validate", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgExecuteRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgValidationResponse" } } }, "description" : "The verdict; `message` is present even when null" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Validate Cypher against the schema without executing it", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/views" : { "get" : { "operationId" : "views_1", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/ViewDebugInfo" }, "type" : "array" } } }, "description" : "Saved views across the world and realm tiers" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "List the acting user's saved views with their cache state", "tags" : [ "Virtual Cypher" ] }, "post" : { "operationId" : "saveView", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSaveViewRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSaveViewResponse" } } }, "description" : "View saved" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSaveViewRejection" } } }, "description" : "Invalid view — bad name, unrunnable body, or the name is taken" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Save a user-authored view (optionally parameterized) into the acting user's world", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/views/{name}" : { "delete" : { "operationId" : "deleteView", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The view's name, as `GET /views` lists it.", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDeleteViewResponse" } } }, "description" : "View deleted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No saved view of that name" } }, "summary" : "Delete a user-authored view from the acting user's world", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/views/{name}/contract" : { "post" : { "operationId" : "generateViewContract", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The view's name, as `GET /views` lists it.", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateContractRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateContractResponse" } } }, "description" : "The drafted contract and what was done with it" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgContractRefusal" } } }, "description" : "The view's output shape is not contractable, or the draft could not be saved" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Draft an ODCS contract for a saved view, optionally sampling, saving and binding it", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/views/{name}/invocation" : { "post" : { "operationId" : "viewInvocation", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The view's name, as `GET /views` lists it.", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgInvokeViewRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgViewInvocationResponse" } } }, "description" : "The runnable cypher for this invocation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Bad view arguments" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Unknown view" } }, "summary" : "Return the runnable Cypher for a saved view invoked with the given arguments", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/views/{name}/refresh" : { "post" : { "operationId" : "refreshView", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The view's name, as `GET /views` lists it.", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgRefreshViewResponse" } } }, "description" : "Whether anything was recomputed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" } }, "summary" : "Force-recompute a materialised view's cache now, ignoring its TTL", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/kg/views/{name}/run" : { "post" : { "operationId" : "runView", "parameters" : [ { "description" : "The user whose world to read. Ignored when the call is authenticated — the signed-in principal always wins — so it is for unauthenticated callers only.", "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The view's name, as `GET /views` lists it.", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgInvokeViewRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgQueryResult" } } }, "description" : "The view's rows, with any producer warnings" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Bad view arguments" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No authenticated principal and no resolvable username" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Unknown view" } }, "summary" : "Run a saved view with the given arguments and return its rows", "tags" : [ "Virtual Cypher" ] } }, "/api/v1/admin/logs" : { "get" : { "description" : "The last N events this process logged, newest last. In-memory and bounded — not a container log, and not a history that survives a restart.", "operationId" : "recent", "parameters" : [ { "description" : "How many lines, newest last. Clamped to the buffer's own size.", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 200, "format" : "int32", "type" : "integer" } }, { "description" : "Only entries at this level or above: ERROR, WARN, INFO, DEBUG, TRACE.", "in" : "query", "name" : "level", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LogTail" } } }, "description" : "Recent log entries, oldest first" } }, "summary" : "Recent log lines from this appliance", "tags" : [ "Diagnostics" ] } }, "/api/v1/admin/principles" : { "delete" : { "description" : "The shipped default resumes. A no-op when nothing was overridden.", "operationId" : "reset", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Reset (or already at the default)" } }, "summary" : "Drop the operator's override", "tags" : [ "Principles" ] }, "get" : { "description" : "The operator's file when one exists, else the shipped default. `overridden` says which.", "operationId" : "read", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Principles" } } }, "description" : "The principles and their provenance" } }, "summary" : "Read the effective principles", "tags" : [ "Principles" ] }, "put" : { "description" : "Replaces the shipped default for this appliance. Plain text/markdown; coding agents receive it verbatim in their authoring brief.", "operationId" : "update", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Saved" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Blank content — use DELETE to return to the shipped default" } }, "summary" : "Set the operator's principles", "tags" : [ "Principles" ] } }, "/api/v1/admin/realms/observability/logs" : { "get" : { "description" : "Guest log lines from the same 200-event ring buffer [LogController] serves. That buffer is shared across this whole process. A realm that last logged more than 200 events ago has aged out of it entirely. Attribution is best-effort: a line from a code path that never set the realm on the MDC comes back with realm null rather than a guess. Capture itself depends on assistant.infrastructure.diagnostics-enabled. When that is off nothing is recorded at all, and captureEnabled says so rather than leaving an empty list to be misread as a quiet realm.", "operationId" : "logs", "parameters" : [ { "description" : "Restrict to one realm's entries. Omit for every realm.", "in" : "query", "name" : "realm", "required" : false, "schema" : { "type" : "string" } }, { "description" : "How many lines, newest last. Clamped to the buffer's own size.", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 200, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RealmLogTail" } } }, "description" : "The current guest log tail" } }, "summary" : "Guest runtime log tail, optionally filtered to one realm", "tags" : [ "Realm observability" ] } }, "/api/v1/admin/realms/observability/metrics" : { "get" : { "description" : "A point-in-time read of the meters this process keeps for realm dispatch, realm builds, and the JVM. Values are cumulative since start.", "operationId" : "metrics", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RealmRuntimeSnapshot" } } }, "description" : "The current snapshot" } }, "summary" : "Realm runtime and JVM metrics", "tags" : [ "Realm observability" ] } }, "/api/v1/admin/system" : { "get" : { "description" : "Heap after the last collection against its ceiling, the container's memory limit, the ingest budget in use and how many ingests wait for it, and whether docling answers and has failed recently, and how many stored chunks have no embedding. A null value is unknown, never zero.", "operationId" : "status_4", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SystemStatus" } } }, "description" : "The appliance's current system status" } }, "summary" : "Memory, ingest queue and document conversion health", "tags" : [ "Diagnostics" ] } }, "/api/v1/agent-platform/agents" : { "get" : { "description" : "Returns every agent the platform hosts, each with its own actions and goals nested inline.", "operationId" : "listAgents_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentListItem" }, "type" : "array" } } }, "description" : "List of agents" } }, "summary" : "List agents", "tags" : [ "Agent platform" ] } }, "/api/v1/agent-platform/goals" : { "get" : { "description" : "Returns every goal the planner knows about, with its tags, example phrasings, and output type.", "operationId" : "listGoals", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/GoalListItem" }, "type" : "array" } } }, "description" : "List of goals" } }, "summary" : "List goals", "tags" : [ "Agent platform" ] } }, "/api/v1/agent-suggestions" : { "get" : { "operationId" : "listAgentSuggestions", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentSuggestion" }, "type" : "array" } } }, "description" : "Every suggestion, open and settled" }, "401" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentSuggestion" }, "type" : "array" } } }, "description" : "No authenticated principal" } }, "summary" : "Suggested colleagues, best first", "tags" : [ "Agent suggestions" ] }, "post" : { "description" : "An open suggestion of the same name is replaced. Nothing is written into the world.", "operationId" : "suggestAgent", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentSuggestion" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "The suggestion as recorded" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No authenticated principal" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "Refused: no evidence, a name in use, an agent to adopt that is not installed" } }, "summary" : "Record a suggested colleague", "tags" : [ "Agent suggestions" ] } }, "/api/v1/agent-suggestions/{id}/adopted" : { "post" : { "operationId" : "markSuggestionAdopted", "parameters" : [ { "description" : "The suggestion's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "The suggestion, adopted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No such suggestion in your world" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "Refused: already settled" } }, "summary" : "Mark a suggestion settled by adopting the realm agent it names", "tags" : [ "Agent suggestions" ] } }, "/api/v1/agent-suggestions/{id}/dismiss" : { "post" : { "operationId" : "dismissAgentSuggestion", "parameters" : [ { "description" : "The suggestion's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "The suggestion, dismissed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No such suggestion in your world" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "Refused: already settled" } }, "summary" : "Dismiss a suggestion", "tags" : [ "Agent suggestions" ] } }, "/api/v1/agent-suggestions/{id}/draft" : { "post" : { "description" : "Writes config/agents/.yml and runs each duty's view once to show what it would act on.", "operationId" : "draftSuggestedAgent", "parameters" : [ { "description" : "The suggestion's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "The suggestion, drafted, with its preview" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "No such suggestion in your world" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SuggestionResponse" } } }, "description" : "Refused: already settled, a suggestion to adopt, or the name is taken" } }, "summary" : "Draft a suggested colleague into the world, unsigned and off duty", "tags" : [ "Agent suggestions" ] } }, "/api/v1/agents" : { "get" : { "description" : "Declared agents, realm-shipped agents, and existing routines gathered into the agent they belong to.", "operationId" : "listAgents", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentView" }, "type" : "array" } } }, "description" : "Every agent in your world, with its stage and needs" }, "401" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentView" }, "type" : "array" } } }, "description" : "No authenticated principal" } }, "summary" : "List the agents in your world", "tags" : [ "Agents" ] } }, "/api/v1/agents/{name}" : { "get" : { "operationId" : "getAgent", "parameters" : [ { "description" : "The agent's name, as the list returns it", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentView" } } }, "description" : "The agent" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentView" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentView" } } }, "description" : "No agent of that name in your world" } }, "summary" : "One agent in your world", "tags" : [ "Agents" ] } }, "/api/v1/agents/{name}/accounts" : { "get" : { "operationId" : "listAgentAccounts", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Slots" } } }, "description" : "Their names; the values are never returned" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Slots" } } }, "description" : "No authenticated principal" } }, "summary" : "The secrets an agent has its own value for, by name", "tags" : [ "Agent accounts" ] } }, "/api/v1/agents/{name}/accounts/{secret}" : { "delete" : { "operationId" : "removeAgentAccount", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The secret's name", "in" : "path", "name" : "secret", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Slots" } } }, "description" : "The secrets it still has its own value for" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Slots" } } }, "description" : "No authenticated principal" } }, "summary" : "Delete an agent's own value for a secret", "tags" : [ "Agent accounts" ] }, "put" : { "description" : "Sent instead of its sponsor's on an API where the agent's identity is own-account.", "operationId" : "setAgentAccount", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The secret's name, as the realm's key declares it", "in" : "path", "name" : "secret", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SecretValue" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Slots" } } }, "description" : "The secrets it now has its own value for" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Slots" } } }, "description" : "No authenticated principal" } }, "summary" : "Keep an agent's own value for a secret", "tags" : [ "Agent accounts" ] } }, "/api/v1/agents/{name}/duties/{duty}/check" : { "post" : { "description" : "Reads the duty's violations view, records upheld, lapsed or unknown, and runs its repair on each violation. Off duty, it runs observing.", "operationId" : "checkAgentDuty", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The duty's name", "in" : "path", "name" : "duty", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DutyCheck" } } }, "description" : "What the check found" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DutyCheck" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DutyCheck" } } }, "description" : "No signed agent of that name holds such a duty" } }, "summary" : "Check one of an agent's duties now", "tags" : [ "Agents" ] } }, "/api/v1/agents/{name}/proposals" : { "get" : { "operationId" : "listAgentProposals", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentProposal" }, "type" : "array" } } }, "description" : "Every proposal, open and settled" }, "401" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentProposal" }, "type" : "array" } } }, "description" : "No authenticated principal" } }, "summary" : "An agent's proposals, newest first", "tags" : [ "Agent reflection" ] } }, "/api/v1/agents/{name}/proposals/{id}/adopt" : { "post" : { "description" : "Refused if the result would grant more than the signed version does.", "operationId" : "adoptAgentProposal", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The proposal's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "The proposal, adopted; the agent now shows unsigned changes" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "No such proposal of this agent's" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "Refused: already settled, or it would widen what the agent may do" } }, "summary" : "Write a proposal into the world as the agent's next version, for its sponsor to sign", "tags" : [ "Agent reflection" ] } }, "/api/v1/agents/{name}/proposals/{id}/dismiss" : { "post" : { "operationId" : "dismissAgentProposal", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The proposal's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "The proposal, dismissed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "No such proposal of this agent's" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "Refused: already settled" } }, "summary" : "Dismiss a proposal", "tags" : [ "Agent reflection" ] } }, "/api/v1/agents/{name}/reflect" : { "post" : { "description" : "Reads its runs, requests and duty checks for the last 30 days. Proposals change only wording, cadence and duties, never what it may do.", "operationId" : "reflectAgent", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "The proposal, with the record it read and the evidence for each change" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "No such agent in your world" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "Refused: the world has no workhorse role, or the model did not answer" } }, "summary" : "Ask an agent to propose a better version of itself from its own record", "tags" : [ "Agent reflection" ] } }, "/api/v1/agents/{name}/retire" : { "post" : { "description" : "Final. Its record of runs and receipts is kept.", "operationId" : "retireAgent", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RetireRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Retired" } } }, "description" : "What was revoked" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Retired" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Retired" } } }, "description" : "No such agent in your world" } }, "summary" : "Retire an agent: off duty for good, its keys revoked and its own credentials deleted", "tags" : [ "Agent accounts" ] } }, "/api/v1/agents/{name}/runs" : { "get" : { "operationId" : "listAgentRuns", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "How many, at most (default 50, at most 500)", "in" : "query", "name" : "limit", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentRun" }, "type" : "array" } } }, "description" : "Its runs: routines, repairs, duty checks and conversations" }, "401" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentRun" }, "type" : "array" } } }, "description" : "No authenticated principal" } }, "summary" : "An agent's runs, newest first", "tags" : [ "Agent runs" ] } }, "/api/v1/agents/{name}/runs/{id}" : { "get" : { "operationId" : "getAgentRun", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The run's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunDetail" } } }, "description" : "The run and its receipts" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunDetail" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunDetail" } } }, "description" : "No such run of this agent's in your world" } }, "summary" : "One run, with its receipts", "tags" : [ "Agent runs" ] } }, "/api/v1/agents/{name}/sign" : { "post" : { "description" : "Only its sponsor or an owner may sign. Refused when nothing has changed since the last signature.", "operationId" : "signAgent", "parameters" : [ { "description" : "The agent's name, as the list returns it", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "The agent, now running the new version" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "No declared agent of that name in your world" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "Refused, with the reason" } }, "summary" : "Sign the agent as its next version", "tags" : [ "Agents" ] } }, "/api/v1/agents/{name}/stage" : { "post" : { "description" : "Off never fires; observing runs with writes suppressed; on may write. Lowering is always allowed.", "operationId" : "setAgentStage", "parameters" : [ { "description" : "The agent's name, as the list returns it", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetStageRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "The agent after the change" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "No such agent, or no such routine on it" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StageResponse" } } }, "description" : "Refused, with the reason: what the agent still needs, or a sponsor raising what only owners may" } }, "summary" : "Move an agent or one of its routines on the ladder", "tags" : [ "Agents" ] } }, "/api/v1/agents/{name}/upcoming" : { "get" : { "description" : "Its scheduled duty checks and routines with when each fires, the requests its last checks say to expect, work in flight, and its recent counts.", "operationId" : "getAgentUpcoming", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Upcoming" } } }, "description" : "The agent's upcoming work" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Upcoming" } } }, "description" : "No authenticated principal" } }, "summary" : "What an agent will do next", "tags" : [ "Agent runs" ] } }, "/api/v1/agents/{name}/upcoming/run" : { "post" : { "operationId" : "runAgentFiringNow", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunNowRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpcomingResponse" } } }, "description" : "The upcoming work; the run appears on the agent's runs" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpcomingResponse" } } }, "description" : "No authenticated principal" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpcomingResponse" } } }, "description" : "Refused: the agent has no such scheduled job" } }, "summary" : "Run one of an agent's scheduled jobs now, outside its schedule", "tags" : [ "Agent runs" ] } }, "/api/v1/agents/{name}/upcoming/skip" : { "post" : { "operationId" : "skipAgentFiring", "parameters" : [ { "description" : "The agent's name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SkipRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpcomingResponse" } } }, "description" : "The upcoming work, with the firing marked skipped" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpcomingResponse" } } }, "description" : "No authenticated principal" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpcomingResponse" } } }, "description" : "Refused: no such job, nothing to skip, already skipped, or a time already past" } }, "summary" : "Skip an agent's next scheduled firing, or postpone it", "tags" : [ "Agent runs" ] } }, "/api/v1/agents/{name}/v1/chat/completions" : { "post" : { "operationId" : "openAiChatCompletions_1", "parameters" : [ { "description" : "The agent, on its own base URL; there `model` is ignored", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChatCompletionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ChatCompletion" } } }, "description" : "The agent's answer; with stream, server-sent chat.completion.chunk events and [DONE]" }, "401" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No API key or session" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No agent of that name may be talked to now" } }, "summary" : "Talk to an agent: the one named as the model, or the one whose base URL this is", "tags" : [ "OpenAI-compatible" ] } }, "/api/v1/agents/{name}/v1/models" : { "get" : { "operationId" : "openAiAgentModels", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ModelList" } } }, "description" : "The agent, as a model" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No API key or session" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No agent of that name may be talked to now" } }, "summary" : "One agent, as the only OpenAI model at its own base URL", "tags" : [ "OpenAI-compatible" ] } }, "/api/v1/agents/{name}/versions" : { "get" : { "operationId" : "agentVersions", "parameters" : [ { "description" : "The agent's name, as the list returns it", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentVersionView" }, "type" : "array" } } }, "description" : "The versions; empty when it has never been signed" }, "401" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentVersionView" }, "type" : "array" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentVersionView" }, "type" : "array" } } }, "description" : "No declared agent of that name in your world" } }, "summary" : "Every signed version of an agent, newest first", "tags" : [ "Agents" ] } }, "/api/v1/api-keys" : { "get" : { "operationId" : "listApiKeys", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "This user's API keys: names and prefixes, never the keys", "tags" : [ "API keys" ] }, "post" : { "operationId" : "mintApiKey", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MintRequest" } } }, "required" : true }, "responses" : { "403" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "The request was authenticated by an API key, which cannot manage keys" } }, "summary" : "Mint a key; the response is the only time the key is shown", "tags" : [ "API keys" ] } }, "/api/v1/api-keys/{id}" : { "delete" : { "operationId" : "revokeApiKey", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Revoke a key immediately", "tags" : [ "API keys" ] } }, "/api/v1/artifacts" : { "get" : { "description" : "Returns artifacts grouped by type.", "operationId" : "listAll", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "List all artifacts", "tags" : [ "Artifacts" ] } }, "/api/v1/artifacts/serve/**" : { "get" : { "description" : "Serves a raw file from the app artifact directories — scoped (serve/{scope}/{path}, where the path may include subfolders) or by flat-name precedence (serve/{name}) — with a content type derived from its extension (html, css, js, json, svg; anything else is octet-stream).", "operationId" : "serve_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } }, "text/html" : { "schema" : { "type" : "object" } } }, "description" : "The file content" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } }, "text/html" : { "schema" : { "type" : "object" } } }, "description" : "No such app artifact" } }, "summary" : "Serve an app artifact", "tags" : [ "Artifacts" ] } }, "/api/v1/artifacts/{type}" : { "get" : { "description" : "Returns an empty list for an unknown type rather than an error. Type is one of the ArtifactType names (case-insensitive).", "operationId" : "listByType", "parameters" : [ { "in" : "path", "name" : "type", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List artifacts of a type", "tags" : [ "Artifacts" ] } }, "/api/v1/artifacts/{type}/{name}" : { "delete" : { "description" : "Type is one of the ArtifactType names (case-insensitive).", "operationId" : "delete", "parameters" : [ { "in" : "path", "name" : "type", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Artifact deleted" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Unknown type" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "No such artifact" } }, "summary" : "Delete an artifact", "tags" : [ "Artifacts" ] }, "get" : { "description" : "Type is one of the ArtifactType names (case-insensitive).", "operationId" : "read_1", "parameters" : [ { "in" : "path", "name" : "type", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The artifact content" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown type" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "No such artifact" } }, "summary" : "Read an artifact's content", "tags" : [ "Artifacts" ] }, "post" : { "description" : "The JSON body carries the content under a content key. Type is one of the ArtifactType names (case-insensitive).", "operationId" : "write", "parameters" : [ { "in" : "path", "name" : "type", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArtifactWriteRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Artifact written" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown type, missing content, or validation failure with a violations array" } }, "summary" : "Create or update an artifact", "tags" : [ "Artifacts" ] } }, "/api/v1/audience/channels" : { "get" : { "description" : "Deliberately unfiltered: a channel nobody has joined is the one somebody needs to find. Only the channel's NAME and its counts are exposed — the content stays gated.", "operationId" : "channels", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChannelsResponse" } } }, "description" : "OK" } }, "summary" : "Channels this world's content declares, with what each unlocks", "tags" : [ "Audience" ] }, "put" : { "description" : "The whole set, not a delta — a client that sends what it displays cannot drift from it. Names are normalised, so what an author wrote and what a user picked are the same channel.", "operationId" : "join", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/JoinRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChannelsResponse" } } }, "description" : "OK" } }, "summary" : "Join or leave channels", "tags" : [ "Audience" ] } }, "/api/v1/auth/oauth2/authorize/{provider}" : { "get" : { "description" : "Redirects to the provider's consent screen when a client app is configured. Without one, an HTML caller is redirected to the chat view to be prompted for credentials, and any other caller gets 409 with a remedy.", "operationId" : "authorize", "parameters" : [ { "in" : "path", "name" : "provider", "required" : true, "schema" : { "type" : "string" } }, { "in" : "header", "name" : "Accept", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "302" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Redirect to the provider consent screen, or to the chat view when no client app is configured and the caller accepts HTML" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No such OAuth2 provider in this world" }, "409" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No client app configured for the provider (non-HTML caller)" } }, "summary" : "Start OAuth2 authorization flow", "tags" : [ "Auth" ] } }, "/api/v1/auth/oauth2/callback" : { "get" : { "description" : "Landing for the provider redirect; renders a human-readable HTML result page rather than JSON.", "operationId" : "callback", "parameters" : [ { "in" : "query", "name" : "code", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "state", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "error", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "text/html" : { "schema" : { "type" : "string" } } }, "description" : "HTML page reporting success or a provider-side failure" }, "400" : { "content" : { "text/html" : { "schema" : { "type" : "string" } } }, "description" : "Missing code or state, or a state this instance never issued" }, "410" : { "content" : { "text/html" : { "schema" : { "type" : "string" } } }, "description" : "The consent screen sat too long and the flow expired" } }, "summary" : "OAuth2 callback — exchanges code for tokens", "tags" : [ "Auth" ] } }, "/api/v1/auth/oauth2/disconnect/{provider}" : { "post" : { "operationId" : "disconnect", "parameters" : [ { "in" : "path", "name" : "provider", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Disconnect every connected account for this OAuth2 provider", "tags" : [ "Auth" ] } }, "/api/v1/auth/oauth2/disconnect/{provider}/{accountId}" : { "post" : { "operationId" : "disconnectAccount", "parameters" : [ { "in" : "path", "name" : "provider", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "accountId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Disconnect one account by id from this OAuth2 provider", "tags" : [ "Auth" ] } }, "/api/v1/auth/oauth2/providers" : { "get" : { "operationId" : "listProviders", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List OAuth2 providers in this world and their status", "tags" : [ "Auth" ] } }, "/api/v1/bootstrap" : { "get" : { "description" : "Supported auth schemes, the preferred interactive login, the current user (null when anonymous), and capability flags. Values come from injected configuration, never guessed from the environment.", "operationId" : "bootstrap", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/BootstrapResponse" } } }, "description" : "OK" } }, "summary" : "Bootstrap info", "tags" : [ "Bootstrap" ] } }, "/api/v1/calendar/connections" : { "get" : { "operationId" : "connections_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/CalendarConnectionsView" } } }, "description" : "OK" } }, "summary" : "Configured calendar providers and this user's connected accounts", "tags" : [ "Calendar" ] } }, "/api/v1/calendar/connections/{accountId}" : { "delete" : { "operationId" : "disconnect_2", "parameters" : [ { "in" : "path", "name" : "accountId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK" } }, "summary" : "Disconnect one of this user's calendar accounts", "tags" : [ "Calendar" ] } }, "/api/v1/calendar/events" : { "get" : { "operationId" : "events", "parameters" : [ { "in" : "query", "name" : "days", "required" : false, "schema" : { "default" : 7, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/EventsResponse" } } }, "description" : "OK" } }, "summary" : "Calendar events across all connected accounts in a time window", "tags" : [ "Calendar" ] } }, "/api/v1/chat" : { "post" : { "description" : "Sends a user message to the assistant. The response is delivered via the SSE stream (GET /stream), not in the POST response body. An SSE stream must be open before sending messages.", "operationId" : "sendMessage", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChatRequest" } } }, "required" : true }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Message accepted" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "No active SSE stream — open /stream first" } }, "summary" : "Send a chat message", "tags" : [ "Chat" ] } }, "/api/v1/chat/attachment" : { "post" : { "description" : "Stores the file, links it to the conversation, and raises an `attachment.received` signal that handlers may claim. Accepts any media type — what happens to a file is decided by dispatch, not by this endpoint. If more than one handler could take it, a question is posted into the conversation.", "operationId" : "sendAttachment", "parameters" : [ { "in" : "query", "name" : "caption", "required" : false, "schema" : { "type" : "string" } }, { "description" : "Realm or capability id to route to. An instruction: it wins outright and proceeds even for irreversible work.", "in" : "query", "name" : "target", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "properties" : { "file" : { "format" : "binary", "type" : "string" } }, "required" : [ "file" ], "type" : "object" } } } }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Attachment accepted" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Empty or oversized file" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "No active chat session" } }, "summary" : "Attach a file to the conversation", "tags" : [ "Chat" ] } }, "/api/v1/chat/attachment/answer" : { "post" : { "description" : "Applies the capability the user chose. Accepts human phrasing (\"yes\", \"add it to my documents\") or a capability id. Omit `attachmentId` to answer the most recent question.", "operationId" : "answer", "parameters" : [ { "in" : "query", "name" : "answer", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "attachmentId", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Outcome status: applied, declined, no-question, unclear, or unavailable" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "No active chat session" } }, "summary" : "Answer a question about an attachment", "tags" : [ "Chat" ] } }, "/api/v1/chat/attachments" : { "get" : { "description" : "Newest first. An import runs in the background and can take over a minute, during which nothing else says it is happening — so this reports the finished ones too, which is what answers \"did it work\" after the fact.", "operationId" : "attachments", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AttachmentActivity" }, "type" : "array" } } }, "description" : "Ingestion records, newest first" } }, "summary" : "What has been done with the files attached to this world", "tags" : [ "Chat" ] } }, "/api/v1/chat/command/{command}" : { "post" : { "description" : "Executes a world slash command by sending it as a chat message. The response is delivered via the SSE stream. An SSE stream must be open before running commands.", "operationId" : "runCommand", "parameters" : [ { "in" : "path", "name" : "command", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CommandRunRequest" } } } }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Command accepted" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Unknown command" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "No active SSE stream — open /stream first" } }, "summary" : "Run a slash command", "tags" : [ "Chat" ] } }, "/api/v1/chat/feedback" : { "post" : { "description" : "Publishes a CHAT-sourced UserFeedbackEvent for the given message text and verdict. Doesn't require an open stream — it's a judgement on a reply already received, not a new turn.", "operationId" : "feedback", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChatFeedbackRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Feedback recorded" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Missing text or an unrecognised verdict" } }, "summary" : "Record thumbs up/down on an assistant reply", "tags" : [ "Chat" ] } }, "/api/v1/chat/history" : { "get" : { "description" : "Returns the full conversation history for the current session.", "operationId" : "history", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Conversation history" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No active session" } }, "summary" : "Get conversation history", "tags" : [ "Chat" ] } }, "/api/v1/chat/image" : { "post" : { "description" : "Uploads an image and optional caption text. The image is persisted to the world and sent to the assistant as a multimodal message. The response is delivered via the SSE stream.", "operationId" : "sendImage", "parameters" : [ { "in" : "query", "name" : "caption", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "properties" : { "image" : { "format" : "binary", "type" : "string" } }, "required" : [ "image" ], "type" : "object" } } } }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Image accepted" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Invalid image" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "No active SSE stream — open /stream first" } }, "summary" : "Send an image (with optional caption) to the assistant", "tags" : [ "Chat" ] } }, "/api/v1/chat/memory/relevant" : { "get" : { "description" : "Uses the same windowed conversation context as the chat loop to find relevant memories. No query needed — derives context from the active conversation.", "operationId" : "relevantMemories", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Relevant memories" } }, "summary" : "Get memories relevant to current conversation", "tags" : [ "Chat" ] } }, "/api/v1/chat/memory/search" : { "post" : { "description" : "Search the user's memories by text similarity, scoped to ACTIVE propositions in the current context. The JSON body requires query; topK defaults to 20 (clamped to 1..30) and minConfidence to 0.5 (clamped to 0..1).", "operationId" : "searchMemory", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SearchMemoryRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Search results" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Missing query" } }, "summary" : "Search memories", "tags" : [ "Chat" ] } }, "/api/v1/chat/process/{processId}" : { "delete" : { "description" : "Kills a running agent process by ID. Use GET /status to find the process ID. This stops any running actions including Docker sandbox processes.", "operationId" : "killProcess", "parameters" : [ { "in" : "path", "name" : "processId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Process killed" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Process not found" } }, "summary" : "Kill a running process", "tags" : [ "Chat" ] } }, "/api/v1/chat/processes" : { "get" : { "description" : "Returns all known agent processes — the chat session and any child processes (actions, tasks, cron). Includes running and recently completed processes.", "operationId" : "listProcesses", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "List of processes" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No active session" } }, "summary" : "List all agent processes", "tags" : [ "Chat" ] } }, "/api/v1/chat/session" : { "delete" : { "description" : "Ends the current chat session and clears state. A new session will be created on next SSE connect.", "operationId" : "endSession", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Session ended" } }, "summary" : "End chat session", "tags" : [ "Chat" ] } }, "/api/v1/chat/sessions" : { "get" : { "description" : "Returns the authenticated user's persisted sessions, newest first, capped at 50 entries — the same cap and ordering the Vaadin sidebar uses. Metadata only (no message bodies).", "operationId" : "listSessions", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/SessionSummaryResponse" }, "type" : "array" } } }, "description" : "Session summaries" } }, "summary" : "List the user's chat sessions", "tags" : [ "Chat sessions" ] } }, "/api/v1/chat/sessions/{sessionId}" : { "delete" : { "description" : "Hard-deletes a session and its messages. Refuses (404) if the session doesn't exist or isn't owned by the caller — [ChatSessionService.deleteSession] can't tell those two cases apart from the outside, and shouldn't: leaking which is which would tell a caller whether an id belongs to someone else. If the deleted session was the one currently attached to this user's live chat stream, it's detached too (`wasActive: true` in the response), so the SPA knows to navigate back to a blank chat rather than keep talking into a session that no longer exists — mirrors ChatSessionsSidebar.onDelete's navigate-to-blank-/chat.", "operationId" : "deleteSession", "parameters" : [ { "in" : "path", "name" : "sessionId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Session deleted" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "No such session, or not owned by the caller" } }, "summary" : "Delete a chat session", "tags" : [ "Chat sessions" ] } }, "/api/v1/chat/status" : { "get" : { "description" : "Returns the status of the user's chat session and any running agent processes. Use this to monitor progress of long-running actions.", "operationId" : "status_3", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Session status" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No active session" } }, "summary" : "Get session and process status", "tags" : [ "Chat" ] } }, "/api/v1/chat/stream" : { "get" : { "description" : "Opens a Server-Sent Events stream for receiving chat responses, background events, and progress updates. Creates a headless chat session if no session exists for this user and no sessionId is given. Pass sessionId to open (or switch to) one of the user's persisted sessions — see GET /chat/sessions for the list. Multiple clients can connect simultaneously and all will receive events.", "operationId" : "stream", "parameters" : [ { "in" : "query", "name" : "sessionId", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "text/event-stream" : { "schema" : { "$ref" : "#/components/schemas/SseEmitter" } } }, "description" : "OK" } }, "summary" : "Open SSE stream", "tags" : [ "Chat" ] } }, "/api/v1/chat/usage" : { "get" : { "description" : "Returns aggregated LLM token usage, cost, and models used across the chat session and all child processes (action invocations, sidecars, cron, webhooks). This gives the true total cost of the session, not just the main chat process. A session with no process yet returns zeros.", "operationId" : "usage", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Aggregated usage, or all zeros when the session has no process yet" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No active session" } }, "summary" : "Get aggregated usage", "tags" : [ "Chat" ] } }, "/api/v1/chat/warm" : { "post" : { "description" : "Call when a turn is imminent (microphone opened, composer focused). Returns immediately; idempotent and cheap to repeat.", "operationId" : "warm", "responses" : { "204" : { "description" : "Warming started, or nothing to warm" } }, "summary" : "Warm the conversation path", "tags" : [ "Chat" ] } }, "/api/v1/commands" : { "get" : { "description" : "Returns all action commands configured in the user's world.", "operationId" : "listCommands", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/ActionCommandConfig" }, "type" : "array" } } }, "description" : "List of commands" } }, "summary" : "List commands", "tags" : [ "Commands" ] }, "post" : { "description" : "Saves a command configuration that maps a slash command to a world action.", "operationId" : "createCommand", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ActionCommandConfig" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Command created/updated" } }, "summary" : "Create or update a command", "tags" : [ "Commands" ] } }, "/api/v1/commands/{command}" : { "delete" : { "description" : "Removes a slash command mapping from the world. Idempotent: deleting a command that does not exist still reports deleted.", "operationId" : "deleteCommand", "parameters" : [ { "description" : "Command name (without leading slash)", "in" : "path", "name" : "command", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Command deleted (or was already absent)" } }, "summary" : "Delete a command", "tags" : [ "Commands" ] } }, "/api/v1/config" : { "get" : { "description" : "Returns the current world configuration from config.yml.", "operationId" : "getConfig", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/WorldConfig" } } }, "description" : "Current config" } }, "summary" : "Get world config", "tags" : [ "Config" ] } }, "/api/v1/config/chat" : { "get" : { "description" : "Returns chat model, temperature, and optional reasoning effort.", "operationId" : "getChatConfig", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Chat config" } }, "summary" : "Get chat config", "tags" : [ "Config" ] }, "put" : { "description" : "Sets chat model, temperature, and optional reasoning effort, persisted to config.yml. A JSON null counts as omitted for every field; a blank model or role still names that field. The effort changes only when the body names reasoningEffort: a value sets it, an empty string clears it, and omitting it keeps it. A body whose only named field is reasoningEffort changes just the effort; any other body, even {}, replaces model, role, and temperature, so {} returns them to the deployment default. A chat config that carries a role resolves the role first and ignores a plain model value; use PUT /chat-model to change what the user talks to.", "operationId" : "updateChatConfig", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LlmConfig" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Chat config updated" } }, "summary" : "Update chat config", "tags" : [ "Config" ] } }, "/api/v1/config/chat-model" : { "put" : { "description" : "Pins the chat model for this world, clearing any role pin so the choice cannot be silently overridden. Blank model clears it and inherits the deployment default; temperature and reasoning effort are kept. A body that names reasoningEffort, even as an empty string, is rejected: set the effort with PUT /chat.", "operationId" : "setChatModel", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LlmConfig" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Chat model updated" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The body names a reasoning effort" } }, "summary" : "Set the model chat uses", "tags" : [ "Config" ] } }, "/api/v1/config/collector" : { "get" : { "description" : "Returns the effective memory-dedup collector settings for this world: enabled, dryRun, matcher, similarityThreshold and cron are resolved against the deployment defaults (never null); the five multi-signal weights are returned as stored (null means the matcher's own default applies).", "operationId" : "getCollectorSettings", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Effective collector settings" } }, "summary" : "Get collector/dedup settings", "tags" : [ "Config" ] }, "put" : { "description" : "Persists this world's collector settings, replacing the stored CollectorConfig. A user sees dry-run and the similarity threshold before the sweep ever touches their data, so both are validated here rather than saved sight-unseen: similarityThreshold and the signal weights must fall in [0, 1], matcher must be 'cosine' or 'multi-signal', and cron must be a valid Spring 6-field expression (seconds minutes hours day-of-month month day-of-week).", "operationId" : "updateCollectorSettings", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CollectorSettingsRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Collector settings updated" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Invalid matcher, threshold, weight, or cron expression" } }, "summary" : "Update collector/dedup settings", "tags" : [ "Config" ] } }, "/api/v1/config/llm-roles" : { "get" : { "description" : "The role→model map realms resolve against (e.g. code_best→gpt-4.1). Empty = inherit deployment defaults.", "operationId" : "getLlmRoles", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "$ref" : "#/components/schemas/LlmConfig" }, "type" : "object" } } }, "description" : "LLM role overrides" } }, "summary" : "Get per-world LLM role overrides", "tags" : [ "Config" ] } }, "/api/v1/config/llm-roles/{roleId}" : { "put" : { "description" : "Maps a role (e.g. code_best) to a model for this world. Send a body with both model and role blank to clear the override (inherit the deployment default). Nothing reads a role's reasoning effort, so a body that names reasoningEffort, even as an empty string, is rejected.", "operationId" : "updateLlmRole", "parameters" : [ { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LlmConfig" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Role override updated" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The body names a reasoning effort" } }, "summary" : "Set or clear an LLM role override", "tags" : [ "Config" ] } }, "/api/v1/config/llms" : { "get" : { "description" : "Returns model, temperature, and reasoning effort for chat, actionCompilerLlm, memoryLlm, apiExplorerLlm, codingLlm, fallbackCodingLlm, rankerLlm, plannerLlm, and lensLlm.", "operationId" : "getLlmConfigs", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "LLM configurations" } }, "summary" : "Get all LLM configurations", "tags" : [ "Config" ] } }, "/api/v1/config/llms/{purpose}" : { "put" : { "description" : "Sets model, temperature, and optional reasoning effort for one of: chat, actionCompilerLlm, memoryLlm, apiExplorerLlm, codingLlm, fallbackCodingLlm, rankerLlm, plannerLlm, lensLlm. A JSON null counts as omitted for every field; a blank model or role still names that field. The effort changes only when the body names reasoningEffort: a value sets it, an empty string clears it, and omitting it keeps it. A body whose only named field is reasoningEffort changes just the effort; any other body, even {}, replaces model, role, and temperature, so {} returns them to the deployment default. Nothing reads the actionCompilerLlm, memoryLlm, or apiExplorerLlm setting at runtime, so any reasoningEffort for them, even an empty string, is rejected with 400.", "operationId" : "updateLlmConfig", "parameters" : [ { "in" : "path", "name" : "purpose", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LlmConfig" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Config updated" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown purpose, unsupported reasoning effort, or reasoning effort on a purpose that does not use it" } }, "summary" : "Update LLM config for a purpose", "tags" : [ "Config" ] } }, "/api/v1/config/mcp-doors" : { "get" : { "description" : "The absolute URLs a client is configured with: `url` is the chat door (`/mcp`, with `/mcp/chat` as the same door spelled as one of a pair) and `developerUrl` is the code door for coding agents. FIELD PRESENCE IS CAPABILITY — `developerUrl` is ABSENT when this server serves no code door, so a client degrades to the chat door rather than to a 404. Same contract, and the same resolver, as the URLs the setup API states before it closes.", "operationId" : "getMcpDoors", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The doors, as absolute URLs" } }, "summary" : "Where this server's MCP doors answer", "tags" : [ "Config" ] } }, "/api/v1/config/mcp-mode" : { "get" : { "description" : "ASSISTANT or DEVELOPER. The default is the deployment's (Worlds declares DEVELOPER; Me leaves it ASSISTANT). Developer mode makes realm install and realm authoring guidance live, and makes MCP orientation lead with realms. Per user, which is per bearer token while a user holds one.", "operationId" : "getMcpMode", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The current mode" } }, "summary" : "What a connected coding agent may do", "tags" : [ "Config" ] }, "put" : { "description" : "Body: {\"mode\": \"ASSISTANT\"|\"DEVELOPER\"}. Persisted to config.yml and live IMMEDIATELY — the gate is read on every call, so an already-connected client simply retries.", "operationId" : "setMcpMode", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/McpModeRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Mode updated" } }, "summary" : "Set what a connected coding agent may do", "tags" : [ "Config" ] } }, "/api/v1/config/models" : { "get" : { "description" : "Returns models (names), modelsWithProvider (name and provider pairs), and the default model. When the provider cannot be queried the lists come back empty with a 200, never an error.", "operationId" : "listModels", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Model names, providers, and the default model" } }, "summary" : "List available models", "tags" : [ "Config" ] } }, "/api/v1/config/notification-routing" : { "get" : { "description" : "Per-user notification routing: per-tier channels + quiet hours. Null tierChannels = inherit deployment defaults.", "operationId" : "getNotificationRouting", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/NotificationRoutingConfig" } } }, "description" : "Notification routing config" } }, "summary" : "Get notification routing", "tags" : [ "Config" ] }, "put" : { "description" : "Sets the per-user routing (tier→channels map + quiet hours). REPLACES the stored routing; persisted to config.yml.", "operationId" : "updateNotificationRouting", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/NotificationRoutingConfig" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Notification routing updated" } }, "summary" : "Update notification routing", "tags" : [ "Config" ] } }, "/api/v1/config/router" : { "get" : { "description" : "Each context with the role or model it uses and the model that resolves; every role with its deployment and world model and the contexts that use it; the chat models available; and the deployment's own model settings, which no world can change yet.", "operationId" : "view", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/RouterView" } } }, "description" : "The chain, resolved" } }, "summary" : "The whole routing chain for this world", "tags" : [ "Model Router" ] } }, "/api/v1/config/router/contexts/{id}" : { "put" : { "description" : "Send `role` or `model`, not both. Send neither to return the context to the deployment default; its reasoning effort is kept.", "operationId" : "setContext", "parameters" : [ { "description" : "A context id, as `GET /config/router` lists it", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ContextRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Changed; takes effect on the next request" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown context, role or model" } }, "summary" : "Point a context at a role, or pin it to a model", "tags" : [ "Model Router" ] } }, "/api/v1/config/router/roles" : { "post" : { "description" : "A role of this world's own: a name, what it is for, and the model it uses. A context can then use it.", "operationId" : "addRole", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/NewRoleRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Added" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Invalid name, taken name, or unknown model" } }, "summary" : "Add a custom role", "tags" : [ "Model Router" ] } }, "/api/v1/config/router/roles/{id}" : { "delete" : { "description" : "Refused while a context still uses it.", "operationId" : "removeRole", "parameters" : [ { "description" : "The custom role's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Deleted" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Not a custom role" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "A context still uses it" } }, "summary" : "Delete a custom role", "tags" : [ "Model Router" ] }, "put" : { "description" : "A blank `model` returns a built-in role to the deployment's choice. A custom role always needs one.", "operationId" : "setRole", "parameters" : [ { "description" : "A role id, as `GET /config/router` lists it", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RoleModelRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Changed; takes effect on the next request" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown role or model" } }, "summary" : "Choose the model a role uses in this world", "tags" : [ "Model Router" ] } }, "/api/v1/config/storage" : { "get" : { "description" : "The graph engine this appliance runs on — a server fact, stated so surfaces never guess it.", "operationId" : "getStorage", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Storage facts" } }, "summary" : "Get storage configuration", "tags" : [ "Config" ] } }, "/api/v1/context" : { "get" : { "operationId" : "context", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/UserContextView" } } }, "description" : "OK" } }, "summary" : "This user's active context and every context name they've used", "tags" : [ "Context" ] } }, "/api/v1/context/current" : { "put" : { "operationId" : "setCurrent", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetContextBody" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Switch this user's active context, creating a new one if the name hasn't been used before", "tags" : [ "Context" ] } }, "/api/v1/context/observation/location" : { "post" : { "description" : "Always returns 204. An unauthenticated push or out-of-range coordinates are silently dropped rather than recorded, so 204 does not guarantee the observation was stored.", "operationId" : "recordLocation", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BrowserLocationRequest" } } }, "required" : true }, "responses" : { "204" : { "description" : "No Content" } }, "summary" : "Push the current browser geolocation for the authenticated user", "tags" : [ "Context" ] } }, "/api/v1/context/timezone" : { "post" : { "description" : "Validates the timezone against ZoneId; rejects invalid zones. Returns 204 whether or not the value changed.", "operationId" : "syncTimeZone", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BrowserTimeZoneRequest" } } }, "required" : true }, "responses" : { "204" : { "description" : "No Content" } }, "summary" : "Sync the browser's IANA timezone for the authenticated user", "tags" : [ "Context" ] } }, "/api/v1/cron" : { "get" : { "description" : "Returns all active cron jobs for the authenticated user's world.", "operationId" : "listJobs", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/CronJobConfig" }, "type" : "array" } } }, "description" : "List of cron jobs" } }, "summary" : "List scheduled jobs", "tags" : [ "Cron" ] }, "post" : { "description" : "Saves the job config to the world and schedules it. If a job with the same name exists, it is replaced. The cron field uses Spring's 6-field expression (seconds minutes hours day-of-month month day-of-week); an unparseable expression is not rejected here — the job is saved but never fires, so validate with /compile-schedule first.", "operationId" : "createJob", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CronJobConfig" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Job created/updated" } }, "summary" : "Create or update a cron job", "tags" : [ "Cron" ] } }, "/api/v1/cron/compile" : { "post" : { "description" : "Describes what the job should do in natural language, compiles an action, and schedules it. This combines action compilation with cron scheduling in a single step.", "operationId" : "compileAndSchedule", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CompileAndScheduleRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Action compiled and job scheduled" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Compilation or scheduling failed" } }, "summary" : "Compile and schedule a cron job", "tags" : [ "Cron" ] } }, "/api/v1/cron/compile-schedule" : { "post" : { "description" : "Converts a schedule description like 'every day at 7am' to a Spring 6-field cron expression using an LLM. The JSON body requires a schedule key. A description the LLM cannot interpret returns 200 with an error key instead of a cron key.", "operationId" : "compileSchedule", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CompileScheduleRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "A cron key on success, or an error key when the description is not a schedule" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Missing schedule" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "LLM call failed" } }, "summary" : "Compile a natural language schedule to a cron expression", "tags" : [ "Cron" ] } }, "/api/v1/cron/{name}" : { "delete" : { "description" : "Cancels the scheduled job and removes its config from the world.", "operationId" : "deleteJob", "parameters" : [ { "description" : "Job name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Job deleted" } }, "summary" : "Delete a cron job", "tags" : [ "Cron" ] } }, "/api/v1/cron/{name}/run" : { "post" : { "description" : "Fires the named cron job outside its normal schedule and runs it inline: the request blocks until the job completes. Output goes to the active chat session when there is one, otherwise to a notification channel.", "operationId" : "runJob", "parameters" : [ { "description" : "Job name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Job ran to completion" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Job not found" } }, "summary" : "Run a job immediately", "tags" : [ "Cron" ] } }, "/api/v1/diagnostics" : { "get" : { "description" : "Returns conversation transcript, LLM-filtered logs, and world state. Makes an LLM call to filter the logs; the diagnosis itself is only produced by the /text variant.", "operationId" : "diagnose", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Get diagnostic report (JSON)", "tags" : [ "Diagnostics" ] } }, "/api/v1/diagnostics/text" : { "get" : { "description" : "Makes up to two LLM calls (log filtering and diagnosis), so expect noticeable latency.", "operationId" : "diagnoseText", "responses" : { "200" : { "content" : { "text/plain" : { "schema" : { "type" : "string" } } }, "description" : "OK" } }, "summary" : "Get diagnostic report as plain text with LLM analysis", "tags" : [ "Diagnostics" ] } }, "/api/v1/directory" : { "get" : { "description" : "Search across all registered directories for skills, APIs, MCP servers, and realms. Optionally filter by type.", "operationId" : "search", "parameters" : [ { "description" : "Search query", "in" : "query", "name" : "q", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Filter by type: SKILL, API, MCP_SERVER, REALM", "in" : "query", "name" : "type", "required" : false, "schema" : { "enum" : [ "SKILL", "API", "MCP_SERVER", "REALM" ], "type" : "string" } }, { "description" : "Exclude already-installed items", "in" : "query", "name" : "excludeInstalled", "required" : false, "schema" : { "default" : true, "type" : "boolean" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/DirectoryEntry" }, "type" : "array" } } }, "description" : "Search results" } }, "summary" : "Search the directory", "tags" : [ "Directory" ] } }, "/api/v1/directory/browse/realms" : { "get" : { "description" : "Returns available realms grouped by provider/account. The complete field is false when a source scan failed or returned partial results.", "operationId" : "browseRealms", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Realms grouped by provider" }, "503" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Directory scan incomplete and no realms available; use Refresh directory to retry" } }, "summary" : "Browse all realms", "tags" : [ "Directory" ] } }, "/api/v1/directory/install" : { "post" : { "description" : "Install a skill, API, MCP server, or realm from a directory entry. Dispatches to the appropriate install mechanism based on type.", "operationId" : "install_2", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DirectoryEntry" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Installed successfully" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Unsupported type or missing source" } }, "summary" : "Install a directory entry", "tags" : [ "Directory" ] } }, "/api/v1/directory/refresh" : { "post" : { "description" : "The GitHub realm scan is cached for the life of the process; this evicts it — the way a newly published realm becomes visible without a restart. Optionally scoped by type.", "operationId" : "refresh", "parameters" : [ { "description" : "Only refresh directories of this type", "in" : "query", "name" : "type", "required" : false, "schema" : { "enum" : [ "SKILL", "API", "MCP_SERVER", "REALM" ], "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DirectoryRefreshResponse" } } }, "description" : "Caches evicted; the next browse re-fetches from the sources" } }, "summary" : "Evict the directory caches so the next browse re-scans the sources", "tags" : [ "Directory" ] } }, "/api/v1/directory/sources" : { "get" : { "description" : "Returns the registered directory sources and their types.", "operationId" : "sources_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "type" : "array" } } }, "description" : "List of directory sources" } }, "summary" : "List directory sources", "tags" : [ "Directory" ] } }, "/api/v1/discovery" : { "get" : { "operationId" : "getCached", "parameters" : [ { "description" : "The discovery name assigned when the API was discovered", "in" : "query", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DiscoveryResult" } } }, "description" : "The cached discovery" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DiscoveryResult" } } }, "description" : "No cached discovery with that name" } }, "summary" : "Get a cached discovery by name", "tags" : [ "API Discovery" ] }, "post" : { "operationId" : "discover", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DiscoverRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DiscoveryResult" } } }, "description" : "OK" } }, "summary" : "Discover an API from a description or URL", "tags" : [ "API Discovery" ] } }, "/api/v1/discovery/cache" : { "get" : { "operationId" : "listCached", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/DiscoveryResult" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List cached API discoveries", "tags" : [ "API Discovery" ] } }, "/api/v1/discovery/install" : { "post" : { "description" : "Looks up a cached discovery result by name and installs it: learns the real spec when possible, or synthesizes one from the endpoints discovery found. The same path Vaadin's Discover tab uses.", "operationId" : "install_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/InstallRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "API installed" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "No cached discovery with that name — run discovery again" } }, "summary" : "Install a discovered API", "tags" : [ "API Discovery" ] } }, "/api/v1/documents" : { "delete" : { "description" : "Delete a document by its URI.", "operationId" : "deleteDocument", "parameters" : [ { "description" : "The document URI, as returned by list or ingest", "in" : "query", "name" : "uri", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Document deleted" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Document not found" } }, "summary" : "Delete a document", "tags" : [ "Documents" ] }, "get" : { "description" : "Returns the current world context's ingested documents with metadata, plus the total chunk count.", "operationId" : "listDocuments_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "List of documents" } }, "summary" : "List documents", "tags" : [ "Documents" ] } }, "/api/v1/documents/ask" : { "post" : { "description" : "Agentic retrieval over the caller's documents, answered in prose with verified citations. An optional window object bounds the search by date: window.field is modified (default), created, or ingested, with window.from inclusive and window.to exclusive. topK defaults to 6 (clamped to 1..25); answer=false skips the composition call and returns sources only; history carries prior turns as Q:/A: lines.", "operationId" : "ask", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AskRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AskResponse" } } }, "description" : "An answer, its sources, or both" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AskResponse" } } }, "description" : "Blank question" }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AskResponse" } } }, "description" : "The agentic documents source is not available in this deployment" } }, "summary" : "Ask a question of your documents", "tags" : [ "Documents" ] } }, "/api/v1/documents/embed-missing" : { "post" : { "description" : "Embeds only the chunks the document was stored without a vector for, without ingesting it again. Answers 202 with a job to follow at GET /documents/ingests/{id}; it settles with the chunks still missing.", "operationId" : "embedMissing", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EmbedMissingRequest" } } }, "required" : true }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobView" } } }, "description" : "Accepted; the job, queued" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobMissing" } } }, "description" : "The caller's world holds no document at that uri" }, "409" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestUnavailable" } } }, "description" : "Nothing can embed; not started" } }, "summary" : "Embed a document's missing chunks as a job", "tags" : [ "Documents" ] } }, "/api/v1/documents/ingests" : { "get" : { "description" : "The caller's running jobs, and those finished within the retention window, newest first.", "operationId" : "list_4", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobList" } } }, "description" : "The caller's jobs" } }, "summary" : "List ingest jobs", "tags" : [ "Documents" ] }, "post" : { "description" : "Answers 202 once the file is received, with a job to follow at GET /documents/ingests/{id}, rather than holding the request until the document is written.", "operationId" : "upload", "parameters" : [ { "in" : "query", "name" : "fromOrgDomain", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "tags", "required" : false, "schema" : { "items" : { "type" : "string" }, "type" : "array" } } ], "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "properties" : { "file" : { "format" : "binary", "type" : "string" } }, "required" : [ "file" ], "type" : "object" } } } }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobView" } } }, "description" : "Accepted; the job, queued" }, "409" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestUnavailable" } } }, "description" : "Nothing can embed; not started" } }, "summary" : "Upload a file to ingest as a job", "tags" : [ "Documents" ] } }, "/api/v1/documents/ingests/url" : { "post" : { "description" : "Answers 202 at once with a job to follow at GET /documents/ingests/{id}.", "operationId" : "ingestUrl_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UrlIngestRequest" } } }, "required" : true }, "responses" : { "202" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobView" } } }, "description" : "Accepted; the job, queued" }, "409" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestUnavailable" } } }, "description" : "Nothing can embed; not started" } }, "summary" : "Ingest a page by URL as a job", "tags" : [ "Documents" ] } }, "/api/v1/documents/ingests/{id}" : { "get" : { "description" : "Where the caller's ingest has got: its stage, embedding progress, and how it ended.", "operationId" : "job", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobView" } } }, "description" : "The job" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/IngestJobMissing" } } }, "description" : "No such job for the caller" } }, "summary" : "Read an ingest job", "tags" : [ "Documents" ] } }, "/api/v1/documents/outline" : { "get" : { "description" : "Headings only, each once: id, title, ordinal, depth and whether it has words of its own. A document ingested before sections were ordered lists none, with a message saying so.", "operationId" : "outline", "parameters" : [ { "description" : "The document's uri, as GET /documents lists it", "in" : "query", "name" : "uri", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DocumentOutlineView" } } }, "description" : "The outline" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DocumentNotFound" } } }, "description" : "The caller's world holds no document at that uri" } }, "summary" : "A document's sections, in reading order", "tags" : [ "Documents" ] } }, "/api/v1/documents/sections" : { "get" : { "description" : "The section at `ordinal` in reading order, as GET /documents/outline numbers them. `text` is the markdown directly under that heading, or null for one that only holds other sections.", "operationId" : "section", "parameters" : [ { "description" : "The document's uri, as GET /documents lists it", "in" : "query", "name" : "uri", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The section's place in reading order, counted from 0", "in" : "query", "name" : "ordinal", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DocumentSectionView" } } }, "description" : "The section" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/DocumentNotFound" } } }, "description" : "No such document in the caller's world, or no section at that ordinal" } }, "summary" : "One section of a document, with its text", "tags" : [ "Documents" ] } }, "/api/v1/documents/tags" : { "put" : { "description" : "Set the tags on an ingested document and every chunk of it, without re-ingesting. The list replaces what was there; blanks are dropped and duplicates collapsed; an empty list removes all tags.", "operationId" : "setTags", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TagsRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/TagsResponse" } } }, "description" : "Tags replaced; the body carries the tags now set" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/TagsResponse" } } }, "description" : "No document at that URI in the caller's world" } }, "summary" : "Replace a document's tags", "tags" : [ "Documents" ] } }, "/api/v1/documents/text" : { "post" : { "description" : "Create a document from inline text content, saved to the world's data/documents directory under the given name; an existing file of that name is overwritten.", "operationId" : "ingestText", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TextIngestRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Document ingested. status is `ingested`, or `ingested_incomplete` when some chunks could not be embedded: the document is kept and text-searchable, chunksWithoutEmbeddings of chunks miss semantic search" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Ingestion failed" } }, "summary" : "Ingest text", "tags" : [ "Documents" ] } }, "/api/v1/documents/upload" : { "post" : { "description" : "Upload a file (PDF, text, HTML, etc.) for ingestion. The optional fromOrgDomain field records which org the file is really from (the upload dialog's From field).", "operationId" : "uploadFile", "parameters" : [ { "in" : "query", "name" : "fromOrgDomain", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "tags", "required" : false, "schema" : { "items" : { "type" : "string" }, "type" : "array" } } ], "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "properties" : { "file" : { "format" : "binary", "type" : "string" } }, "required" : [ "file" ], "type" : "object" } } } }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Document ingested. status is `ingested`, or `ingested_incomplete` when some chunks could not be embedded: the document is kept and text-searchable, chunksWithoutEmbeddings of chunks miss semantic search" } }, "summary" : "Upload and ingest a file", "tags" : [ "Documents" ] } }, "/api/v1/documents/url" : { "post" : { "description" : "Fetch and ingest a document from a URL (web page, PDF, etc.). The optional fromOrgDomain field overrides the publisher domain inferred from the URL host.", "operationId" : "ingestUrl", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UrlIngestRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Document ingested. status is `ingested`, or `ingested_incomplete` when some chunks could not be embedded: the document is kept and text-searchable, chunksWithoutEmbeddings of chunks miss semantic search" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Fetch or ingestion failed" } }, "summary" : "Ingest from URL", "tags" : [ "Documents" ] } }, "/api/v1/email/connections" : { "get" : { "operationId" : "connections", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/EmailConnectionsView" } } }, "description" : "OK" } }, "summary" : "Configured email providers and this user's connected accounts", "tags" : [ "Email" ] } }, "/api/v1/email/connections/{accountId}" : { "delete" : { "operationId" : "disconnect_1", "parameters" : [ { "in" : "path", "name" : "accountId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK" } }, "summary" : "Disconnect one of this user's email accounts", "tags" : [ "Email" ] } }, "/api/v1/email/threads" : { "get" : { "operationId" : "threads", "parameters" : [ { "in" : "query", "name" : "days", "required" : false, "schema" : { "default" : 14, "format" : "int32", "type" : "integer" } }, { "in" : "query", "name" : "maxPerAccount", "required" : false, "schema" : { "default" : 50, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ThreadsResponse" } } }, "description" : "OK" } }, "summary" : "Recent email threads across all connected accounts", "tags" : [ "Email" ] } }, "/api/v1/embeddings" : { "get" : { "description" : "`configured` false means document features are off — `reason` says so in the words to show somebody, and names the command that fixes it.", "operationId" : "status", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Whether documents can be embedded, and with what", "tags" : [ "Embeddings" ] }, "post" : { "description" : "RE-EMBEDS EVERYTHING. Vector indexes are created at a model's own dimensions, so a different model means every stored vector is wrong until it is recomputed — this drops the indexes, walks each store, re-embeds, and rebuilds them at the new width, restoring the previous model if any of that fails. Setting the first model on an appliance that has none is the cheap case: there is nothing to re-embed yet.", "operationId" : "change", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChangeRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Changed" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No such model, or it could not be reached" }, "409" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "A reindex is already running" } }, "summary" : "Change the embedding model", "tags" : [ "Embeddings" ] } }, "/api/v1/halt" : { "delete" : { "operationId" : "resume", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "Lifted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Lift the halt: every agent back as it was", "tags" : [ "Agents" ] }, "get" : { "operationId" : "getHalt", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "The halt, or halted false" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "No authenticated principal" } }, "summary" : "Whether every agent in your world is stopped", "tags" : [ "Agents" ] }, "post" : { "description" : "Every routine and duty is off from the next tick, and a run already going is refused its writes. Lifting the halt restores every stage.", "operationId" : "halt", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "Halted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HaltResponse" } } }, "description" : "No world" } }, "summary" : "Stop every agent in your world", "tags" : [ "Agents" ] } }, "/api/v1/handlers" : { "get" : { "description" : "Includes handlers that are installed but not adopted — the state that is otherwise invisible, and the usual reason a realm appears to do nothing.", "operationId" : "list_8", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List the handlers in your world and whether each is switched on", "tags" : [ "Handlers" ] } }, "/api/v1/handlers/set-enabled" : { "post" : { "description" : "Adopting a realm-shipped handler that writes. Scoped to the authenticated user's world; no parameter can name another.", "operationId" : "setEnabled", "parameters" : [ { "in" : "query", "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "enabled", "required" : true, "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Set" }, "404" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "No such handler in your world" } }, "summary" : "Switch a handler in your own world on or off", "tags" : [ "Handlers" ] } }, "/api/v1/hints" : { "get" : { "operationId" : "all", "parameters" : [ { "description" : "Asking surface: 'me' or 'console'. Omit for every surface's hints.", "in" : "query", "name" : "surface", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/Hint" }, "type" : "array" } } }, "description" : "Every hint the caller should see" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Get all hints for the acting user and surface", "tags" : [ "Hints" ] } }, "/api/v1/hints/category" : { "get" : { "operationId" : "byCategory", "parameters" : [ { "description" : "Category name to filter by", "in" : "query", "name" : "category", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Asking surface: 'me' or 'console'. Omit for every surface's hints.", "in" : "query", "name" : "surface", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/Hint" }, "type" : "array" } } }, "description" : "The category's hints" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Get hints by category", "tags" : [ "Hints" ] } }, "/api/v1/hints/random" : { "get" : { "description" : "Returns an empty body when every hint is excluded.", "operationId" : "random", "parameters" : [ { "description" : "Hint ids to suppress, so a client can avoid repeating recently shown hints", "in" : "query", "name" : "exclude", "required" : false, "schema" : { "items" : { "type" : "string" }, "type" : "array" } }, { "description" : "Asking surface: 'me' or 'console'. Omit for every surface's hints.", "in" : "query", "name" : "surface", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Hint" } } }, "description" : "One hint, or an empty body when every hint is excluded" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Get a random hint", "tags" : [ "Hints" ] } }, "/api/v1/hints/schedule" : { "get" : { "description" : "`cron` is the six-field expression the schedule runs on, in the user's own zone; null when tips are off.", "operationId" : "schedule", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/TipScheduleView" } } }, "description" : "The schedule in force" }, "401" : { "description" : "Not authenticated" } }, "summary" : "When a tip is posted to the acting user's inbox", "tags" : [ "Hints" ] }, "put" : { "description" : "Takes effect at once: the job is rescheduled before this returns. NEVER removes it.", "operationId" : "changeSchedule", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TipSchedule" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/TipScheduleView" } } }, "description" : "The schedule now in force" }, "400" : { "description" : "Unknown frequency, or an hour outside 0-23" }, "401" : { "description" : "Not authenticated" } }, "summary" : "Change when a tip is posted to the acting user's inbox", "tags" : [ "Hints" ] } }, "/api/v1/identity-link-proposals/{id}/accept" : { "post" : { "description" : "Links the identity with HUMAN provenance, updates any realm bridge, and dismisses the proposal.", "operationId" : "accept", "parameters" : [ { "description" : "Notification id of the proposal", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Linked" }, "403" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Not permitted — the proposal targets another world" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No such pending proposal" }, "422" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Proposal payload could not be parsed" } }, "summary" : "Accept an identity-link proposal", "tags" : [ "Identity Link Proposals" ] } }, "/api/v1/identity-link-proposals/{id}/reject" : { "post" : { "description" : "Tombstones the identity — automatic matching will never re-propose it — and dismisses the proposal.", "operationId" : "reject", "parameters" : [ { "description" : "Notification id of the proposal", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Rejected" }, "403" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Not permitted — the proposal targets another world" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "No such pending proposal" }, "422" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Proposal payload could not be parsed" } }, "summary" : "Reject an identity-link proposal", "tags" : [ "Identity Link Proposals" ] } }, "/api/v1/images/{filename}" : { "get" : { "description" : "Scoped to the authenticated user. The content type is derived from the file extension.", "operationId" : "serve", "parameters" : [ { "in" : "path", "name" : "filename", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Image bytes with the image's own content type" }, "403" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Not an image file" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Image not found" } }, "summary" : "Serve an image by filename", "tags" : [ "Images" ] } }, "/api/v1/kg/studio/execute" : { "post" : { "operationId" : "studioExecute", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgExecuteRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgQueryResult" } } }, "description" : "The finished result" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Bad params or args" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "Execute verbatim Cypher through the virtual-cypher engine, synchronously", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/generate" : { "post" : { "operationId" : "studioGenerate", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgAskRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateResponse" } } }, "description" : "The generated cypher, its verdict, and what the engine will do" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Generation failed" } }, "summary" : "Generate Cypher and an execution explanation for a question, without running it", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/kill/{runId}" : { "post" : { "operationId" : "studioKill", "parameters" : [ { "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgKillResponse" } } }, "description" : "Whether the kill landed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "Cancel an in-flight run by id (owner-guarded)", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/refine" : { "post" : { "operationId" : "studioRefine", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgRefineRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgGenerateResponse" } } }, "description" : "The revised cypher, its verdict, and what the engine will do" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Refinement failed" } }, "summary" : "Revise existing Cypher per an instruction, without running it", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/runs" : { "get" : { "operationId" : "studioRuns", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/KgInFlightRun" }, "type" : "array" } } }, "description" : "The caller's in-flight runs, newest first" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "List the caller's in-flight virtual-cypher runs", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/schema" : { "get" : { "operationId" : "studioSchema", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSchemaResponse" } } }, "description" : "The schema snapshot; empty lists and no `refreshedAt` when none exists" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "The caller's own graph schema — labels, properties, relationship triples", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/scopes" : { "get" : { "operationId" : "studioScopes", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgScopeListResponse" } } }, "description" : "The scopes; an expired scope is already absent" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "List the caller's live captured scopes, newest first", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/scopes/{name}" : { "delete" : { "operationId" : "studioDeleteScope", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgScopeDeleteResponse" } } }, "description" : "Whether anything was deleted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "Delete one of the caller's captured scopes", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/scopes/{name}/pin" : { "post" : { "operationId" : "studioPinScope", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgScopeInfo" } } }, "description" : "The scope as stored, now with no expiry" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No such scope" } }, "summary" : "Pin one of the caller's captured scopes", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/validate" : { "post" : { "operationId" : "studioValidate", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgExecuteRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgValidationResponse" } } }, "description" : "The verdict; `message` is present even when null" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "Validate Cypher against the schema without executing it", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/views" : { "get" : { "operationId" : "studioViews", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/ViewDebugInfo" }, "type" : "array" } } }, "description" : "Saved views across the world and realm tiers" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "List the caller's saved views with their cache state", "tags" : [ "Virtual Cypher (user)" ] }, "post" : { "operationId" : "studioSaveView", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSaveViewRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSaveViewResponse" } } }, "description" : "View saved" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgSaveViewRejection" } } }, "description" : "Invalid view — bad name, unrunnable body, or the name is taken" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "Save a user-authored view (optionally parameterized) into the caller's world", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/views/{name}" : { "delete" : { "operationId" : "studioDeleteView", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgDeleteViewResponse" } } }, "description" : "View deleted" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "No saved view of that name" } }, "summary" : "Delete a user-authored view from the caller's world", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/views/{name}/invocation" : { "post" : { "operationId" : "studioViewInvocation", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgInvokeViewRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgViewInvocationResponse" } } }, "description" : "The runnable cypher for this invocation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Bad view arguments" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "Unknown view" } }, "summary" : "Return the runnable Cypher for a saved view invoked with the given arguments", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/kg/studio/views/{name}/refresh" : { "post" : { "operationId" : "studioRefreshView", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgRefreshViewResponse" } } }, "description" : "Whether anything was recomputed" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/KgErrorResponse" } } }, "description" : "not authenticated" } }, "summary" : "Force-recompute a materialised view's cache now, ignoring its TTL", "tags" : [ "Virtual Cypher (user)" ] } }, "/api/v1/learn/apis" : { "post" : { "operationId" : "connectApi", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConnectApiRequest" } } }, "required" : true }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Spec unreachable or unparseable, or a token missing for the mode" } }, "summary" : "Connect an API to this world, so it can be learned", "tags" : [ "Learning" ] } }, "/api/v1/learn/apis/modes" : { "get" : { "operationId" : "apiModes", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApiModesResponse" } } }, "description" : "OK" } }, "summary" : "API auth modes this appliance can connect with, and their fields", "tags" : [ "Learning" ] } }, "/api/v1/learn/apis/{name}" : { "put" : { "operationId" : "updateLearnSourceApi", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConnectApiRequest" } } }, "required" : true }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Spec unreachable or unparseable, or a token missing for the mode" }, "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not an API this user connected" } }, "summary" : "Change a connected API. The spec is fetched first; a failed fetch changes nothing", "tags" : [ "Learning" ] } }, "/api/v1/learn/databases" : { "post" : { "operationId" : "connect", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConnectDatabaseRequest" } } }, "required" : true }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Unknown engine, unreachable, no driver, or an empty schema" } }, "summary" : "Connect a database to this world, so it can be learned", "tags" : [ "Learning" ] } }, "/api/v1/learn/databases/engines" : { "get" : { "operationId" : "engines", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EnginesResponse" } } }, "description" : "OK" } }, "summary" : "Database engines this appliance carries a driver for, and their connection fields", "tags" : [ "Learning" ] } }, "/api/v1/learn/databases/{name}" : { "put" : { "operationId" : "updateLearnSourceDatabase", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConnectDatabaseRequest" } } }, "required" : true }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Unreachable, bad credential, no driver, or an empty schema" }, "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not a database this user connected" } }, "summary" : "Change a connected database. Tested first; a failed test changes nothing", "tags" : [ "Learning" ] } }, "/api/v1/learn/sources" : { "get" : { "operationId" : "sources", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SourcesResponse" } } }, "description" : "OK" } }, "summary" : "Sources this appliance can reach, described from metadata alone", "tags" : [ "Learning" ] } }, "/api/v1/learn/sources/{name}" : { "delete" : { "operationId" : "disconnectLearnSource", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not a source this user connected" } }, "summary" : "Disconnect a source: its connection, stored secret and provisional realm", "tags" : [ "Learning" ] } }, "/api/v1/learn/sources/{name}/connection" : { "get" : { "operationId" : "learnSourceConnection", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SourceConnection" } } }, "description" : "Not a source this user connected" } }, "summary" : "How a connected source is connected, for an edit form. Secrets are never returned", "tags" : [ "Learning" ] } }, "/api/v1/learn/sources/{name}/install" : { "delete" : { "operationId" : "uninstallLearnSourceRealm", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No provisional realm is installed for this source" } }, "summary" : "Uninstall a source's provisional realm. The connection stays", "tags" : [ "Learning" ] } }, "/api/v1/learn/sources/{name}/learn" : { "post" : { "operationId" : "learn", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LearnRequest" } } } }, "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No such source, or it is unreachable" }, "422" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "The source's kind is detected but not yet learnable" } }, "summary" : "Mine, curate and probe a source. Writes nothing — returns the proposal to review", "tags" : [ "Learning" ] } }, "/api/v1/learn/{id}" : { "delete" : { "operationId" : "discardLearnReview", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No such review for this user — unknown, expired, or already discarded" } }, "summary" : "Discard a held review. It wrote nothing, so this undoes nothing", "tags" : [ "Learning" ] }, "get" : { "operationId" : "proposal", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "OK" } }, "summary" : "A proposal already learned in this session", "tags" : [ "Learning" ] } }, "/api/v1/learn/{id}/answer" : { "post" : { "operationId" : "answerLearningQuestion", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AnswerRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProposalResponse" } } }, "description" : "OK" } }, "summary" : "Answer one open question — keep, reverse, or fall back to what the store asserted", "tags" : [ "Learning" ] } }, "/api/v1/learn/{id}/install" : { "post" : { "operationId" : "install", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/InstalledResponse" } } }, "description" : "OK" } }, "summary" : "Install as a PROVISIONAL realm and rebuild the world — queryable immediately", "tags" : [ "Learning" ] } }, "/api/v1/learn/{id}/promote" : { "post" : { "operationId" : "promote", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PromoteRequest" } } }, "required" : true }, "responses" : { "409" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "A realm of that name already exists — promotion never overwrites" } }, "summary" : "Promote a reviewed provisional realm to a name you stand behind", "tags" : [ "Learning" ] } }, "/api/v1/lenses" : { "get" : { "operationId" : "list", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "List saved lenses", "tags" : [ "Lenses" ] }, "put" : { "operationId" : "create", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateLensRequest" } } }, "required" : true }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Blank name or script" } }, "summary" : "Create or update a saved lens", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/briefing" : { "post" : { "operationId" : "briefing", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BriefingLensRequest" } } } }, "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No briefing lens defined in this world" } }, "summary" : "Render the briefing lens over a chosen time window", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/chat" : { "post" : { "operationId" : "chat", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LensChatRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Ask a question grounded in a lens's focused entities", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/runs/{runId}" : { "get" : { "description" : "Returns the redacted envelope: RUNNING while in flight, the final result once settled.", "operationId" : "lensRun", "parameters" : [ { "description" : "The background run id carried by the RUNNING envelope", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "401" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No such run for this user" } }, "summary" : "Poll a background lens run", "tags" : [ "Headless Invocation" ] } }, "/api/v1/lenses/runs/{runId}/kill" : { "post" : { "description" : "Best-effort stop; the run settles CANCELLED.", "operationId" : "killLensRun", "parameters" : [ { "description" : "The background run to stop", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "401" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No such run for this user" } }, "summary" : "Kill a background lens run", "tags" : [ "Headless Invocation" ] } }, "/api/v1/lenses/{id}/present" : { "post" : { "operationId" : "present", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunSavedRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Return a saved lens's presented content", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/{id}/run" : { "post" : { "operationId" : "run_2", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunSavedRequest" } } } }, "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Lens not found" } }, "summary" : "Open a saved lens and return how many entities it focused", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/{id}/views" : { "post" : { "operationId" : "views", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunSavedRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "List the views available for a saved lens", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/{id}/views/{view}" : { "post" : { "operationId" : "renderView", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "view", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunSavedRequest" } } } }, "responses" : { "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Lens or view not found" }, "409" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "View does not apply to this lens" } }, "summary" : "Render one named view of a saved lens", "tags" : [ "Lenses" ] } }, "/api/v1/lenses/{lensId}/invoke" : { "post" : { "description" : "Run an authored lens by id and return a redacted, typed result envelope. `background=true` returns a RUNNING envelope immediately; `waitSeconds=N` waits that long then hands back the RUNNING envelope instead of blocking. For those deferred modes the envelope's executionId is a run handle: poll GET /lenses/runs/{runId} with it. A synchronous invocation returns the final result directly; its executionId is not pollable.", "operationId" : "invokeLens", "parameters" : [ { "description" : "The authored lens id", "in" : "path", "name" : "lensId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Run on a worker and return a RUNNING envelope immediately", "in" : "query", "name" : "background", "required" : false, "schema" : { "default" : false, "type" : "boolean" } }, { "description" : "Wait up to this many seconds for the run to settle, then return the envelope as it stands rather than blocking", "in" : "query", "name" : "waitSeconds", "required" : false, "schema" : { "format" : "int64", "type" : "integer" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/InvokeRequest" } } } }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Arguments do not match the lens's declared parameters, or the body has a field other than args/idempotencyKey" }, "401" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No such lens" } }, "summary" : "Invoke a named lens", "tags" : [ "Headless Invocation" ] } }, "/api/v1/memory/remember" : { "post" : { "description" : "Persists one already-formed statement as an ACTIVE proposition in the caller's context. If an ACTIVE proposition with the same text (modulo case and surrounding whitespace) already exists, returns that proposition instead of inserting a duplicate.", "operationId" : "remember", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RememberFactRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Remember a fact", "tags" : [ "Memory" ] } }, "/api/v1/models/in-use" : { "get" : { "operationId" : "inUse", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/InUseResponse" } } }, "description" : "Models in use, with providers" } }, "summary" : "Which models are actually in use, and whether any is hosted", "tags" : [ "Models" ] } }, "/api/v1/next-steps" : { "get" : { "description" : "`status` is DONE, TODO or UNKNOWN. UNKNOWN means the step's own query could not be answered — `detail` says why — and must not be shown as outstanding work: a surface that nags on a broken query nags hardest when the appliance is least well.", "operationId" : "nextSteps", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Every declared onboarding step, with whether it is already done", "tags" : [ "Next steps" ] } }, "/api/v1/next-steps/{id}/dismissed" : { "put" : { "description" : "The only remembered thing here: every other answer is derived from the graph. Dismissing does NOT mark a step done — it is still evaluated, so one waved away and then done anyway still reports DONE.", "operationId" : "setDismissed", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DismissRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Say this step is not going to be done, or take that back", "tags" : [ "Next steps" ] } }, "/api/v1/notifications" : { "delete" : { "operationId" : "dismissAll", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "All notifications dismissed" } }, "summary" : "Dismiss all notifications", "tags" : [ "Notifications" ] }, "get" : { "description" : "Newest first.", "operationId" : "list_3", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/NotificationNode" }, "type" : "array" } } }, "description" : "List of notifications" } }, "summary" : "List the authenticated user's notifications", "tags" : [ "Notifications" ] }, "post" : { "operationId" : "create_2", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Notification" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/NotificationNode" } } }, "description" : "Notification created" }, "202" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/NotificationNode" } } }, "description" : "Received, but the admission filter judged it below the user's bar; nothing was stored" } }, "summary" : "Create a notification for the authenticated user", "tags" : [ "Notifications" ] } }, "/api/v1/notifications/read-all" : { "post" : { "operationId" : "markAllRead", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "All notifications marked as read" } }, "summary" : "Mark all notifications as read", "tags" : [ "Notifications" ] } }, "/api/v1/notifications/unread" : { "get" : { "operationId" : "unread", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/NotificationNode" }, "type" : "array" } } }, "description" : "List of unread notifications" } }, "summary" : "List the authenticated user's unread notifications", "tags" : [ "Notifications" ] } }, "/api/v1/notifications/{id}" : { "delete" : { "operationId" : "dismiss", "parameters" : [ { "description" : "Notification ID", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Notification dismissed" } }, "summary" : "Dismiss a notification", "tags" : [ "Notifications" ] } }, "/api/v1/notifications/{id}/read" : { "post" : { "operationId" : "markRead", "parameters" : [ { "description" : "Notification ID", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Notification marked as read" } }, "summary" : "Mark notification as read", "tags" : [ "Notifications" ] } }, "/api/v1/onboarding/run" : { "post" : { "operationId" : "run_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OnboardingRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/OnboardingStartResponse" } } }, "description" : "OK" } }, "summary" : "Start the Get-to-Know-Me onboarding flow", "tags" : [ "Onboarding" ] } }, "/api/v1/onboarding/sources" : { "get" : { "operationId" : "availableSources", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/AvailableSourcesResponse" } } }, "description" : "OK" } }, "summary" : "Get available onboarding sources", "tags" : [ "Onboarding" ] } }, "/api/v1/onboarding/status/{jobId}" : { "get" : { "operationId" : "status_2", "parameters" : [ { "in" : "path", "name" : "jobId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/OnboardingStatusResponse" } } }, "description" : "OK" } }, "summary" : "Get onboarding job status", "tags" : [ "Onboarding" ] } }, "/api/v1/openai/v1/chat/completions" : { "post" : { "operationId" : "openAiChatCompletions", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ChatCompletionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ChatCompletion" } } }, "description" : "The agent's answer; with stream, server-sent chat.completion.chunk events and [DONE]" }, "401" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No API key or session" }, "404" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No agent of that name may be talked to now" } }, "summary" : "Talk to an agent: the one named as the model, or the one whose base URL this is", "tags" : [ "OpenAI-compatible" ] } }, "/api/v1/openai/v1/models" : { "get" : { "operationId" : "openAiModels", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ModelList" } } }, "description" : "The agents, as models" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorBody" } } }, "description" : "No API key or session" } }, "summary" : "The agents you can talk to now, as OpenAI models", "tags" : [ "OpenAI-compatible" ] } }, "/api/v1/profile" : { "get" : { "operationId" : "profile", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ProfileView" } } }, "description" : "OK" } }, "summary" : "This user's display name and home location", "tags" : [ "Profile" ] } }, "/api/v1/profile/display-name" : { "put" : { "operationId" : "setDisplayName", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DisplayNameBody" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Rename this user — pushes to WorkOS and heals proposition prose, same as the Vaadin profile editor", "tags" : [ "Profile" ] } }, "/api/v1/profile/home" : { "put" : { "operationId" : "setHomeLocation", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HomeLocationBody" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/ProfileView" } } }, "description" : "OK" } }, "summary" : "Set or clear this user's home location", "tags" : [ "Profile" ] } }, "/api/v1/profile/preferences" : { "get" : { "operationId" : "preferences", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/PreferencesView" } } }, "description" : "OK" } }, "summary" : "This user's greeting and login-hints preferences", "tags" : [ "Profile" ] }, "put" : { "operationId" : "setPreferences", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PreferencesBody" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/PreferencesView" } } }, "description" : "OK" } }, "summary" : "Set this user's greeting and login-hints preferences", "tags" : [ "Profile" ] } }, "/api/v1/profile/voice" : { "get" : { "operationId" : "voice", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/VoiceProfileView" } } }, "description" : "OK" } }, "summary" : "This user's voice preferences, and whether voice is available at all in this deployment", "tags" : [ "Profile" ] }, "put" : { "operationId" : "setVoice", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/VoiceUpdateBody" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/VoiceProfileView" } } }, "description" : "OK" } }, "summary" : "Set this user's preferred voice and effects", "tags" : [ "Profile" ] } }, "/api/v1/realms" : { "get" : { "description" : "Returns all realms installed in the world — the shipped Realms view's rows, filtered to installed, so this listing and a `MATCH (r:Realm)` query can never disagree.", "operationId" : "listRealms", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "List of realms" } }, "summary" : "List installed realms", "tags" : [ "Realms" ] }, "post" : { "description" : "Installs a realm by cloning a git repository into the world. Use owner/repo shorthand for GitHub repos, or a full URL. Optionally specify a branch or commit SHA via the ref field.", "operationId" : "addRealm", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AddRealmRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Realm installed" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Realm already exists" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Install failed" } }, "summary" : "Install a realm", "tags" : [ "Realms" ] } }, "/api/v1/realms/gaps" : { "get" : { "description" : "What this world could add: installable realms (directory minus installed), inert APIs with the key that unlocks each, and structural gaps. The REST projection of the same CapabilitySuggester that serves the suggest_capabilities MCP tool.", "operationId" : "gaps", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Capability gaps" } }, "summary" : "Capability gaps", "tags" : [ "Realms" ] } }, "/api/v1/realms/refresh" : { "post" : { "description" : "Rebuilds the caller's world so realm references added or removed since the last build take effect — the runtime-install step for a realm referenced by local path, which nothing clones and no per-realm update can see before it is loaded.", "operationId" : "refreshRealms", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World rebuilt; response lists the realms now loaded" } }, "summary" : "Refresh the world's realms", "tags" : [ "Realms" ] } }, "/api/v1/realms/update-all" : { "post" : { "description" : "Updates Git-backed realm references; local-directory references are already live.", "operationId" : "updateAllRealms", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Update results for each realm" } }, "summary" : "Update all realms", "tags" : [ "Realms" ] } }, "/api/v1/realms/updates" : { "get" : { "description" : "Reads each git-backed realm's remote refs (ls-remote — no objects are transferred) and compares to the local checkout. `behind` is null when it cannot be determined.", "operationId" : "realmUpdates", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Per-realm update state" } }, "summary" : "Which installed realms have a newer version upstream", "tags" : [ "Realms" ] } }, "/api/v1/realms/{name}" : { "delete" : { "description" : "Removes an installed realm from the world.", "operationId" : "removeRealm", "parameters" : [ { "description" : "Realm name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Realm removed" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Nothing installed answers to that name; the message lists what is installed" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "The realm is served from a manifest or directory this world does not own" } }, "summary" : "Remove a realm", "tags" : [ "Realms" ] } }, "/api/v1/realms/{name}/icon" : { "get" : { "description" : "The image the realm declares as `icon` in realm.yml. 404 when the realm has none, names one that is missing, or names one outside its own directory.", "operationId" : "icon", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "format" : "byte", "type" : "string" } } }, "description" : "The icon" }, "404" : { "content" : { "*/*" : { "schema" : { "format" : "byte", "type" : "string" } } }, "description" : "No icon" } }, "summary" : "A realm's icon", "tags" : [ "Realms" ] } }, "/api/v1/realms/{name}/update" : { "post" : { "description" : "Pulls the latest changes for a realm backed by a git checkout. A realm loaded from a local path reference has no checkout to pull; it reports as already live.", "operationId" : "updateRealm", "parameters" : [ { "description" : "Realm name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Realm updated, or already live for a local reference" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Realm not found" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Update failed" } }, "summary" : "Update a realm", "tags" : [ "Realms" ] } }, "/api/v1/receipts/verify" : { "get" : { "description" : "Walks the chain: each receipt must follow the one before it and hash to what it says it does.", "operationId" : "verifyReceipts", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Verification" } } }, "description" : "How many receipts, whether the chain is intact, and where it first breaks" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Verification" } } }, "description" : "No authenticated principal" } }, "summary" : "Check that every receipt still says what it said when it was written", "tags" : [ "Agent runs" ] } }, "/api/v1/requests" : { "get" : { "operationId" : "listRequests", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentRequest" }, "type" : "array" } } }, "description" : "The requests, with any whose time ran out marked expired" }, "401" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/AgentRequest" }, "type" : "array" } } }, "description" : "No authenticated principal" } }, "summary" : "Every request raised in your world, newest first", "tags" : [ "Requests" ] } }, "/api/v1/requests/{id}" : { "get" : { "operationId" : "getRequest", "parameters" : [ { "description" : "The request's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentRequest" } } }, "description" : "The request" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentRequest" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AgentRequest" } } }, "description" : "No such request in your world" } }, "summary" : "One request", "tags" : [ "Requests" ] } }, "/api/v1/requests/{id}/decision" : { "post" : { "description" : "Approving calls the request's verb as you, through the gateway. Rejecting needs a reason.", "operationId" : "decideRequest", "parameters" : [ { "description" : "The request's id", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DecisionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DecisionResponse" } } }, "description" : "The request after the decision" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DecisionResponse" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DecisionResponse" } } }, "description" : "No such request in your world" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DecisionResponse" } } }, "description" : "Refused: already decided or expired, a rejection with no reason, or no such decision" } }, "summary" : "Approve or reject a request", "tags" : [ "Requests" ] } }, "/api/v1/samples" : { "delete" : { "description" : "Every `:_Sample` node whatever loaded it — what you run before showing this world to somebody who should only see real records.", "operationId" : "clear", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Cleared" } }, "summary" : "Remove all sample data", "tags" : [ "Sample data" ] }, "get" : { "description" : "One entry per set, with how many nodes it put in.", "operationId" : "list_2", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "What sample data is loaded", "tags" : [ "Sample data" ] }, "post" : { "description" : "Nodes are marked `:_Sample` and tagged with the set name, so the set can be removed later without touching anything real. Loading the same set twice merges rather than duplicates.", "operationId" : "load", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SampleSetRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Loaded" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "The set was refused; the body lists why" } }, "summary" : "Load a sample set", "tags" : [ "Sample data" ] } }, "/api/v1/samples/export" : { "post" : { "description" : "Returns exactly the body `POST /samples` accepts, so an exported file can be loaded elsewhere with no translation. Select by `source` (what one sample set loaded) or by `labels`, or both; labels alone take every record of that type in the world. Defaults to shape-only: labels, property keys and edges, with the values and ids replaced. Ask for `WITH_VALUES` deliberately — a support case rarely needs them, and ids are routinely email addresses.", "operationId" : "export", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ExportRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/SampleDataExportResponse" } } }, "description" : "The set" } }, "summary" : "Read records out as a loadable sample set", "tags" : [ "Sample data" ] } }, "/api/v1/samples/{name}" : { "delete" : { "description" : "Every node that set loaded, and nothing else.", "operationId" : "remove", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "OK" } }, "summary" : "Remove one sample set", "tags" : [ "Sample data" ] } }, "/api/v1/sensor/capabilities" : { "post" : { "description" : "The sensor's verb catalog for the consent groups its user has enabled. Replaces the previous catalog; an empty list withdraws every verb.", "operationId" : "capabilities", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilitiesRequest" } } }, "required" : true }, "responses" : { "200" : { "description" : "OK" } }, "summary" : "Publish what this machine can be asked to do", "tags" : [ "Sensor" ] } }, "/api/v1/sensor/events" : { "post" : { "operationId" : "ingest", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SensorBatchRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SensorBatchResponse" } } }, "description" : "Per-event receipts with accepted/deduplicated/rejected counts" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SensorBatchResponse" } } }, "description" : "Blank source" } }, "summary" : "Ingest a batch of sensor events for the authenticated user", "tags" : [ "Sensor" ] } }, "/api/v1/sensor/outbox" : { "get" : { "description" : "Held up to ~25 seconds. 200 with a command, or 204 when the window closes empty.", "operationId" : "poll", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SensorCommand" } } }, "description" : "OK" } }, "summary" : "Long-poll for the next sensor command", "tags" : [ "Sensor" ] } }, "/api/v1/sensor/outbox/{id}/result" : { "post" : { "operationId" : "result", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "additionalProperties" : true, "description" : "The verb's own result, verbatim. The shape belongs to the verb, not to this endpoint, which stores it and never reads it.", "type" : "object" } } }, "required" : true }, "responses" : { "200" : { "description" : "OK" } }, "summary" : "Report a command's result", "tags" : [ "Sensor" ] } }, "/api/v1/signal-types" : { "get" : { "operationId" : "catalogue", "parameters" : [ { "in" : "query", "name" : "days", "required" : false, "schema" : { "default" : 30, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/SignalTypeInfo" }, "type" : "array" } } }, "description" : "Signal types, busiest first" } }, "summary" : "List the signal types this world has received, with their fields and how often", "tags" : [ "Signals" ] } }, "/api/v1/signals/backfill/run" : { "post" : { "description" : "Replay signals from every time-window ingestion source over the past N hours. Redeliveries are deduped, so this is safe to re-run.", "operationId" : "backfill", "parameters" : [ { "description" : "Lookback window in hours (e.g. 5 for the last 5 hours)", "in" : "query", "name" : "hours", "required" : false, "schema" : { "format" : "double", "type" : "number" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Backfill report with per-source results" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Invalid lookback duration" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Backfill failed" } }, "summary" : "Backfill signals from the trailing window", "tags" : [ "Signals" ] } }, "/api/v1/skills" : { "get" : { "operationId" : "listSkills_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/SkillSummary" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List the authenticated user's installed skills", "tags" : [ "Skills" ] } }, "/api/v1/sources/{kind}/{id}" : { "get" : { "description" : "Returns a 302 whose Location header carries the raw external URL, preserving URL fragments through to the browser's final navigation.", "operationId" : "redirect", "parameters" : [ { "in" : "path", "name" : "kind", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "302" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Redirect to the external URL" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Unknown source kind, or an id the resolver refuses" } }, "summary" : "Redirect to the external URL of a cited source", "tags" : [ "Sources" ] } }, "/api/v1/themes" : { "get" : { "operationId" : "listThemes", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "OK" } }, "summary" : "List available themes", "tags" : [ "Themes" ] } }, "/api/v1/themes/{name}.css" : { "get" : { "operationId" : "getThemeCss", "parameters" : [ { "description" : "Theme name; the path is the name with a .css suffix", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "text/css" : { "schema" : { "type" : "string" } } }, "description" : "The theme stylesheet" }, "404" : { "content" : { "text/css" : { "schema" : { "type" : "string" } } }, "description" : "Unknown theme" } }, "summary" : "Get theme CSS", "tags" : [ "Themes" ] } }, "/api/v1/themes/{name}/apply" : { "post" : { "description" : "Sets the theme on the in-memory user; the choice is not persisted across restarts by this endpoint.", "operationId" : "applyTheme", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Theme applied" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Unknown theme" } }, "summary" : "Apply a theme for the current user's session", "tags" : [ "Themes" ] } }, "/api/v1/threads" : { "get" : { "operationId" : "listThreads", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ThreadList" } } }, "description" : "The threads" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ThreadList" } } }, "description" : "No authenticated principal" } }, "summary" : "Your threads, most recently active first", "tags" : [ "Threads" ] }, "post" : { "operationId" : "createThread", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateThreadRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Thread" } } }, "description" : "The thread" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Thread" } } }, "description" : "No authenticated principal" } }, "summary" : "Start a thread", "tags" : [ "Threads" ] } }, "/api/v1/threads/{id}" : { "get" : { "operationId" : "getThread", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/View" } } }, "description" : "The thread" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/View" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/View" } } }, "description" : "No thread of yours with that id" } }, "summary" : "A thread, its messages, and the agents still answering", "tags" : [ "Threads" ] } }, "/api/v1/threads/{id}/messages" : { "post" : { "description" : "Attachments are resolved and frozen now: a view is run, a request read, a record taken as you send it.", "operationId" : "postThreadMessage", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PostMessageRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ThreadMessage" } } }, "description" : "The message as posted" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ThreadMessage" } } }, "description" : "Nothing to post" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ThreadMessage" } } }, "description" : "No authenticated principal" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ThreadMessage" } } }, "description" : "No thread of yours with that id" } }, "summary" : "Post in a thread; every agent you @mention answers in it", "tags" : [ "Threads" ] } }, "/api/v1/tours" : { "get" : { "description" : "Shipped, realm-contributed and user-saved alike. `presentation` is whatever the tour's YAML declared, carried through untouched — the client owns that vocabulary.", "operationId" : "list_7", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourListResponse" } } }, "description" : "Every tour declared for the acting user's world" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Every tour this world offers", "tags" : [ "Tours" ] } }, "/api/v1/tours/import" : { "post" : { "description" : "`yaml` carries a tour FILE, not a JSON rendering of a tour: the exchange format and the storage format are the same thing, so what is imported is what a realm would ship and what `/export` returned. A name a realm or this world already owns is refused with 409 rather than written, because the loader keeps what it finds and the write would never load.", "operationId" : "import", "parameters" : [ { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourImportRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourListResponse" } } }, "description" : "The tours as stored, with the ids this world gave them" }, "401" : { "description" : "Basic-auth challenge failed" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourRefusal" } } }, "description" : "A tour of that name is already shipped here — `error` names which one" } }, "summary" : "Store a tour somebody exported, or a client recorded", "tags" : [ "Tours" ] } }, "/api/v1/tours/{id}" : { "delete" : { "description" : "A realm's tour and the world's own are not deletable here — they leave when whatever shipped them leaves. `deleted` is false rather than a 404 for those: the tour exists, it is simply not the caller's to remove.", "operationId" : "delete_3", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourDeletedResponse" } } }, "description" : "Whether a saved tour was removed" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Delete a tour this user saved", "tags" : [ "Tours" ] } }, "/api/v1/tours/{id}/export" : { "get" : { "description" : "What a user hands to somebody else. Round-trips through the import below, and is byte-for-byte the shape this server loads from a realm — so a tour that was exported, edited and re-imported is not a second dialect.", "operationId" : "export_1", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "text/plain" : { "schema" : { "type" : "string" } } }, "description" : "The tour's YAML" }, "401" : { "description" : "Basic-auth challenge failed" }, "404" : { "content" : { "text/plain" : { "schema" : { "$ref" : "#/components/schemas/TourRefusal" } } }, "description" : "No tour of that id in this world" } }, "summary" : "One tour as the file it would be", "tags" : [ "Tours" ] } }, "/api/v1/tours/{id}/steps/{index}/status" : { "post" : { "description" : "Answered WHEN THE STEP IS REACHED, not when the tour is fetched: a tour changes the world as it walks through it, so a verdict computed at load time describes a world that no longer exists. UNKNOWN means the step's own query could not be answered — `detail` says why — and a client should run the step anyway. Repeating a step is visible and recoverable; silently skipping one is neither. A POST rather than a GET because the tour's collected parameters are the body: the condition worth writing is usually about the thing the user just named, and without them the only expressible preconditions are those that depend on no answer.", "operationId" : "stepStatus", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "in" : "path", "name" : "index", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "in" : "query", "name" : "username", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourStepStatusRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TourStepStatusResponse" } } }, "description" : "DONE, TODO or UNKNOWN" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Is this step already satisfied?", "tags" : [ "Tours" ] } }, "/api/v1/ui/surface" : { "post" : { "description" : "The surface's own tour dictionary, sent verbatim. The assistant may then offer to fill the fields it names. `states` and `dynamic` are a tour's business and are ignored. Controls are recorded and never pressed.", "operationId" : "publish", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SurfaceDictionary" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SurfaceResponse" } } }, "description" : "Recorded; the fields now offered are echoed back" }, "401" : { "description" : "Basic-auth challenge failed" } }, "summary" : "Declare what this screen can be told to do", "tags" : [ "Surface" ] } }, "/api/v1/views/{name}/invoke" : { "post" : { "description" : "Run an authored Virtual-Cypher view by name and return a redacted, typed result envelope. The runnable query is never exposed.", "operationId" : "invokeView", "parameters" : [ { "description" : "The authored view name", "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/InvokeRequest" } } } }, "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Arguments do not match the view's declared parameters, or the body has a field other than args/idempotencyKey" }, "401" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Not authenticated" }, "404" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "No such view" } }, "summary" : "Invoke a named view", "tags" : [ "Headless Invocation" ] } }, "/api/v1/voice/session" : { "get" : { "description" : "Returns a short-lived Deepgram token and the settings it is for. The durable key never leaves this appliance. Ask again for each socket.", "operationId" : "session", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/VoiceSessionView" } } }, "description" : "The credential and the settings it is for" }, "409" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/VoiceSessionView" } } }, "description" : "This world has no Deepgram key — voice is not set up" } }, "summary" : "Open a voice session", "tags" : [ "Voice" ] } }, "/api/v1/watches" : { "get" : { "operationId" : "list_1", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "List watches", "tags" : [ "Watches" ] }, "post" : { "operationId" : "create_1", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateWatchRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Create a watch", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}" : { "delete" : { "operationId" : "delete_2", "parameters" : [ { "description" : "The watch to delete", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Delete a watch", "tags" : [ "Watches" ] }, "get" : { "operationId" : "get", "parameters" : [ { "description" : "The watch to return", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Get a watch", "tags" : [ "Watches" ] }, "patch" : { "operationId" : "update_1", "parameters" : [ { "description" : "The watch to update", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateWatchRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Update a watch", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/changes" : { "get" : { "operationId" : "changes", "parameters" : [ { "description" : "The watch whose changes to list", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Return only changes recorded after this run; omit for every change the watch has recorded", "in" : "query", "name" : "afterRunId", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "List changes since a run", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/deliveries" : { "get" : { "operationId" : "deliveries", "parameters" : [ { "description" : "The watch whose delivery attempts to list", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "List delivery attempts for a watch", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/diff" : { "get" : { "description" : "Four legal parameter combinations: both run ids (baseRunId + targetRunId); both ISO instants (baseAt + targetAt); targetRunId alone compares it against the previous complete run; no parameters compares latest versus previous.", "operationId" : "compare", "parameters" : [ { "description" : "The watch whose runs to compare", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The run to compare FROM; pair it with targetRunId", "in" : "query", "name" : "baseRunId", "required" : false, "schema" : { "type" : "string" } }, { "description" : "The run to compare TO; given alone it is compared against the previous complete run", "in" : "query", "name" : "targetRunId", "required" : false, "schema" : { "type" : "string" } }, { "description" : "ISO instant to compare FROM, resolved to the run current at that time; pair it with targetAt", "in" : "query", "name" : "baseAt", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "ISO instant to compare TO, resolved to the run current at that time", "in" : "query", "name" : "targetAt", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } } ], "responses" : { "400" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "Any other parameter combination" } }, "summary" : "Compare two runs", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/diffs/{diffId}" : { "get" : { "operationId" : "diff", "parameters" : [ { "description" : "The watch that owns the diff", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The persisted diff to return", "in" : "path", "name" : "diffId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Get a persisted diff", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/runs" : { "get" : { "operationId" : "runs", "parameters" : [ { "description" : "The watch whose runs to list", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "List a watch's runs", "tags" : [ "Watches" ] }, "post" : { "description" : "Repeat calls with the same idempotencyKey return the original run instead of running again.", "operationId" : "run", "parameters" : [ { "description" : "The watch to run now", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RunWatchRequest" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Run a watch now", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/runs/{runId}" : { "get" : { "operationId" : "run_6", "parameters" : [ { "description" : "The watch that owns the run", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The run to return", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Get one watch run", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/runs/{runId}/snapshot" : { "get" : { "operationId" : "snapshot", "parameters" : [ { "description" : "The watch that owns the run", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The run whose snapshot to return", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Get a run's canonical snapshot", "tags" : [ "Watches" ] } }, "/api/v1/watches/{watchId}/runs/{runId}/subjects/{source}/{entityId}" : { "get" : { "operationId" : "subject", "parameters" : [ { "description" : "The watch that owns the run", "in" : "path", "name" : "watchId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The run whose snapshot holds the subject", "in" : "path", "name" : "runId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The subject's source system, taken from the href the snapshot itself emitted; \"world\" is the local graph", "in" : "path", "name" : "source", "required" : true, "schema" : { "type" : "string" } }, { "description" : "The subject's id within that source, taken from the same href", "in" : "path", "name" : "entityId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "object" } } }, "description" : "OK" } }, "summary" : "Get one subject from a run's snapshot", "tags" : [ "Watches" ] } }, "/api/v1/webhooks" : { "get" : { "description" : "Shows the local and public webhook URLs (detecting a Tailscale funnel when present), configured sources, and queued sources.", "operationId" : "status_1", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Webhook status" } }, "summary" : "Webhook status", "tags" : [ "Webhooks" ] } }, "/api/v1/webhooks/{source}" : { "post" : { "description" : "Receives a JSON payload from an external system. If the source has a configured action, the event is processed immediately; otherwise the payload type is inferred and the event is queued until the user configures an action via the UI. Provider URL-validation handshakes (such as an endpoint.url_validation event) are answered synchronously with the scheme-specific response body instead of the processed/queued shape.", "operationId" : "receiveWebhook_1", "parameters" : [ { "description" : "Source identifier for the webhook (e.g., 'github', 'stripe')", "in" : "path", "name" : "source", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "format" : "byte", "type" : "string" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Event processed successfully, or handshake response body" }, "202" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Event queued (unknown source, awaiting configuration)" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Body is not valid JSON, or not an object or array of objects" }, "401" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Signature verification or tenant resolution failed" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Processing error" } }, "summary" : "Receive a webhook event", "tags" : [ "Webhooks" ] } }, "/api/v1/webhooks/{source}/{token}" : { "post" : { "description" : "Receives a JSON payload from an external system. If the source has a configured action, the event is processed immediately; otherwise the payload type is inferred and the event is queued until the user configures an action via the UI. Provider URL-validation handshakes (such as an endpoint.url_validation event) are answered synchronously with the scheme-specific response body instead of the processed/queued shape.", "operationId" : "receiveWebhook", "parameters" : [ { "description" : "Source identifier for the webhook (e.g., 'github', 'stripe')", "in" : "path", "name" : "source", "required" : true, "schema" : { "type" : "string" } }, { "description" : "High-entropy per-install tenancy token generated at webhook registration; identifies the tenant for sources using path-token tenancy, absent otherwise", "in" : "path", "name" : "token", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "format" : "byte", "type" : "string" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Event processed successfully, or handshake response body" }, "202" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Event queued (unknown source, awaiting configuration)" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Body is not valid JSON, or not an object or array of objects" }, "401" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Signature verification or tenant resolution failed" }, "500" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Processing error" } }, "summary" : "Receive a webhook event", "tags" : [ "Webhooks" ] } }, "/api/v1/world" : { "get" : { "description" : "Returns a summary of the world including counts and names of skills, APIs, actions, types, and MCP servers.", "operationId" : "overview", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World summary" } }, "summary" : "World overview", "tags" : [ "World" ] } }, "/api/v1/world/actions" : { "get" : { "description" : "Returns all compiled actions and goals in the world.", "operationId" : "listActions", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "List of action specs" } }, "summary" : "List actions", "tags" : [ "World" ] } }, "/api/v1/world/apis" : { "get" : { "description" : "Returns all loaded APIs with their descriptions and auth requirements.", "operationId" : "listApis", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "List of APIs" } }, "summary" : "List APIs", "tags" : [ "World" ] }, "post" : { "description" : "Saves an API entry to the world. Refresh world to activate.", "operationId" : "addApi", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AddApiRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "API saved" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Missing url" } }, "summary" : "Add an API", "tags" : [ "World" ] } }, "/api/v1/world/apis/learn" : { "post" : { "description" : "Introspects an API from a spec URL (OpenAPI or GraphQL endpoint) and returns metadata. Does not save.", "operationId" : "learnApi", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LearnApiRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Learned API info" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Missing url, or the spec could not be learned" } }, "summary" : "Learn an API", "tags" : [ "World" ] } }, "/api/v1/world/apis/{name}" : { "delete" : { "description" : "Removes an API entry from the world.", "operationId" : "deleteApi", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "API removed" } }, "summary" : "Remove an API", "tags" : [ "World" ] } }, "/api/v1/world/documents" : { "get" : { "description" : "Returns files in the world data/documents directory.", "operationId" : "listDocuments", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "List of documents" } }, "summary" : "List world documents", "tags" : [ "World" ] } }, "/api/v1/world/documents/{name}" : { "get" : { "description" : "Returns the content of a document from the world data/documents directory, truncated to the first 10000 characters.", "operationId" : "readDocument", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Document content" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Document not found" } }, "summary" : "Read a world document", "tags" : [ "World" ] } }, "/api/v1/world/mcp" : { "get" : { "description" : "Returns MCP servers reachable from this world: those the world itself configured, plus any wired in at the installation level, each with its tool count and tool names.", "operationId" : "listMcp", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "$ref" : "#/components/schemas/McpServerInfo" }, "type" : "array" } } }, "description" : "List of MCP servers" } }, "summary" : "List MCP servers", "tags" : [ "World" ] } }, "/api/v1/world/mcp/{name}" : { "delete" : { "description" : "Removes an MCP server entry from the world.", "operationId" : "deleteMcp", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "MCP server removed" } }, "summary" : "Remove an MCP server", "tags" : [ "World" ] } }, "/api/v1/world/personalities" : { "get" : { "description" : "Returns all personalities in the world with slug, display name, source, and active status.", "operationId" : "listPersonalities", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "List of personalities" } }, "summary" : "List available personalities", "tags" : [ "World" ] }, "post" : { "description" : "Creates a world-tier personality — blank, or duplicated from an existing one via `from`. Validated by rendering before it counts; a persona that cannot render is not created.", "operationId" : "createPersonality", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreatePersonalityRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Created" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Refused — slug taken, unknown `from`, or the persona does not render" } }, "summary" : "Create a personality", "tags" : [ "World" ] } }, "/api/v1/world/personalities/{slug}" : { "delete" : { "description" : "The active personality is refused — switch first. Realm personalities are removed by uninstalling their realm.", "operationId" : "deletePersonality", "parameters" : [ { "in" : "path", "name" : "slug", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Deleted" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Refused — active, realm-owned, or unknown" } }, "summary" : "Delete a world-tier personality", "tags" : [ "World" ] }, "get" : { "description" : "The identity and jinja sections of one personality, with whether it is editable. Realm personalities are readable but read-only — duplicating one into the world is how it becomes editable.", "operationId" : "personalitySections", "parameters" : [ { "in" : "path", "name" : "slug", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "The personality's files" }, "404" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Unknown personality" } }, "summary" : "Read a personality's files", "tags" : [ "World" ] }, "put" : { "description" : "Sets the active personality for the current world.", "operationId" : "switchPersonality", "parameters" : [ { "in" : "path", "name" : "slug", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Personality switched" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Unknown personality; the response lists the available slugs" } }, "summary" : "Switch active personality", "tags" : [ "World" ] } }, "/api/v1/world/personalities/{slug}/files" : { "put" : { "description" : "World-tier personalities only; a realm personality answers with the duplicate-first instruction. The save is validated by rendering, and rolls back if the persona no longer renders.", "operationId" : "updatePersonality", "parameters" : [ { "in" : "path", "name" : "slug", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdatePersonalityRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Saved" }, "400" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Refused — read-only, unknown files, or the persona does not render" } }, "summary" : "Save a personality's files", "tags" : [ "World" ] } }, "/api/v1/world/progress" : { "get" : { "description" : "What a world being made for the first time is up to. Empty once there is nothing in progress.", "operationId" : "provisioning", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "The current phase, or an empty object" } }, "summary" : "World provisioning progress", "tags" : [ "World" ] } }, "/api/v1/world/skills" : { "get" : { "description" : "Returns all loaded skills with their descriptions.", "operationId" : "listSkills", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { "type" : "string" }, "type" : "object" }, "type" : "array" } } }, "description" : "List of skills" } }, "summary" : "List skills", "tags" : [ "World" ] }, "post" : { "description" : "Creates a new local skill with a SKILL.md following the Agent Skills Specification.", "operationId" : "createSkill", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateSkillRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Skill created" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Invalid input" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Skill already exists" } }, "summary" : "Create a local skill", "tags" : [ "World" ] } }, "/api/v1/world/skills/refresh" : { "post" : { "description" : "Clears the local GitHub skills disk cache and rebuilds the world so skills are re-fetched on next load.", "operationId" : "refreshGitHubSkillsCache", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Skills cache cleared and world rebuilt" } }, "summary" : "Refresh GitHub skills", "tags" : [ "World" ] } }, "/api/v1/world/skills/{name}" : { "delete" : { "description" : "Removes a skill entry from the world.", "operationId" : "deleteSkill", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { "type" : "string" }, "type" : "object" } } }, "description" : "Skill removed" } }, "summary" : "Remove a skill", "tags" : [ "World" ] } }, "/api/v1/world/tools" : { "get" : { "description" : "Returns all tools grouped by category (skills, apiTools, mcpTools, documentTools, progressTools, statusTools).", "operationId" : "listTools", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Categorized tool list" } }, "summary" : "List all tools available to the LLM", "tags" : [ "World" ] } }, "/api/v1/world/types" : { "get" : { "description" : "Returns all dynamic type definitions in the world.", "operationId" : "listTypes", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "items" : { "additionalProperties" : { }, "type" : "object" }, "type" : "array" } } }, "description" : "List of types" } }, "summary" : "List dynamic types", "tags" : [ "World" ] } }, "/api/v1/worlds" : { "get" : { "description" : "Lists all worlds for the current user.", "operationId" : "listWorlds", "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World listing" } }, "summary" : "List worlds", "tags" : [ "Worlds" ] }, "post" : { "description" : "Creates a new world from the default template. The JSON body requires a name key; the name must not contain slashes or dots-dots.", "operationId" : "createWorld", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateWorldRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World created" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Missing or invalid name" }, "409" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World already exists" } }, "summary" : "Create world", "tags" : [ "Worlds" ] } }, "/api/v1/worlds/{name}" : { "delete" : { "description" : "Deletes a world. Cannot delete the currently active world.", "operationId" : "deleteWorld", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World deleted" }, "400" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Cannot delete active world" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World not found" } }, "summary" : "Delete world", "tags" : [ "Worlds" ] } }, "/api/v1/worlds/{name}/reset" : { "post" : { "description" : "Wipes the world's `config/` directory and re-clones it from the default template. **The `data/` directory is left untouched** — documents, vibe-coded apps, tasks, learnings, generated artifacts and entered secrets are preserved. To wipe everything including data, delete the world instead.", "operationId" : "factoryReset", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World config reset to defaults; data preserved" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World not found" } }, "summary" : "Factory reset world", "tags" : [ "Worlds" ] } }, "/api/v1/worlds/{name}/switch" : { "post" : { "description" : "Switches the current user to a different world.", "operationId" : "switchWorld", "parameters" : [ { "in" : "path", "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "Switched successfully" }, "404" : { "content" : { "*/*" : { "schema" : { "additionalProperties" : { }, "type" : "object" } } }, "description" : "World not found" } }, "summary" : "Switch world", "tags" : [ "Worlds" ] } } }, "security" : [ { "apiKeyAuth" : [ ] }, { "basicAuth" : [ ] } ], "servers" : [ { "description" : "Generated server url", "url" : "http://localhost:38025" } ], "tags" : [ { "description" : "Durable alert-diff subscriptions over saved Lenses", "name" : "Watches" }, { "description" : "Conversations you and your agents share", "name" : "Threads" }, { "description" : "Accept or reject an inbox identity-link proposal", "name" : "Identity Link Proposals" }, { "description" : "Protocol for the local sensor app on the user's machine: event ingest and the command outbox", "name" : "Sensor" }, { "description" : "An agent proposes a better version of itself, for its sponsor to sign", "name" : "Agent reflection" }, { "description" : "Channels this world's content declares, and the ones you have joined", "name" : "Audience" }, { "description" : "Resolve cited source links to their external home", "name" : "Sources" }, { "description" : "The appliance's architectural principles, as coding agents receive them", "name" : "Principles" }, { "description" : "What a connected screen says it can be told to do", "name" : "Surface" }, { "description" : "The signed-in user's own scoped view of the Cypher studio surface", "name" : "Virtual Cypher (user)" }, { "description" : "Stylesheet theme management", "name" : "Themes" }, { "description" : "Manage world artifacts: documents, sites, code, data, diagrams", "name" : "Artifacts" }, { "description" : "Colleagues worth hiring, with the evidence", "name" : "Agent suggestions" }, { "description" : "Get-to-Know-Me flow", "name" : "Onboarding" }, { "description" : "Browser voice sessions", "name" : "Voice" }, { "description" : "Manage world realms", "name" : "Realms" }, { "description" : "Chat with the assistant via SSE streaming", "name" : "Chat" }, { "description" : "Manage world slash commands", "name" : "Commands" }, { "description" : "Read the platform's goal and agent catalogue", "name" : "Agent platform" }, { "description" : "The signed-in user's calendar events", "name" : "Calendar" }, { "description" : "API discovery from a natural-language description (LLM-driven) or directly from a spec URL", "name" : "API Discovery" }, { "description" : "Keys the signed-in user mints to reach this world from code", "name" : "API keys" }, { "description" : "The colleagues in your world", "name" : "Agents" }, { "description" : "Inspect and manage world resources: skills, APIs, MCP servers, documents, tools, and personalities", "name" : "World" }, { "description" : "Serve world images", "name" : "Images" }, { "description" : "Admin: re-apply graph projection policy to already-extracted propositions", "name" : "KG Reprojection" }, { "description" : "Manage ingested documents and sources", "name" : "Documents" }, { "description" : "Admin: plan and run typed actions synthesised from a user's repositories and realm APIs", "name" : "Code Actions" }, { "description" : "Search for installable skills, APIs, MCP servers, and realms", "name" : "Directory" }, { "description" : "On-demand catchup / meeting-prep run", "name" : "Catchup" }, { "description" : "What is set up, and what is not", "name" : "Next steps" }, { "description" : "Author, list and run saved lenses; the productized consumer path is Headless Invocation", "name" : "Lenses" }, { "description" : "The signed-in user's email threads", "name" : "Email" }, { "description" : "The signed-in user's named memory contexts, and which one is active", "name" : "Context" }, { "description" : "An agent's own credentials, and retiring it", "name" : "Agent accounts" }, { "description" : "The signed-in user's connected email accounts", "name" : "Email" }, { "description" : "Tells a fresh client how to log in and who (if anyone) is signed in", "name" : "Bootstrap" }, { "description" : "Models available to this appliance", "name" : "Models" }, { "description" : "Talk to an agent with any OpenAI client", "name" : "OpenAI-compatible" }, { "description" : "The embedding model, and switching it", "name" : "Embeddings" }, { "description" : "Manage world configuration", "name" : "Config" }, { "description" : "Compile and manage world actions", "name" : "Actions" }, { "description" : "Guided walks through a surface, shipped as content", "name" : "Tours" }, { "description" : "Admin: inspect node decorators and fire them on demand instead of waiting for the scheduled tick", "name" : "KG Decoration" }, { "description" : "Contexts, roles and the models they resolve to", "name" : "Model Router" }, { "description" : "Manage scheduled jobs in the world", "name" : "Cron" }, { "description" : "OAuth2 authentication for external APIs", "name" : "Auth" }, { "description" : "Manage user worlds", "name" : "Worlds" }, { "description" : "Push observations into the user-context layer", "name" : "Context" }, { "description" : "Manage user notifications", "name" : "Notifications" }, { "description" : "Development diagnostic tools; present only when assistant.infrastructure.diagnostics-enabled is true", "name" : "Diagnostics" }, { "description" : "List and delete the user's persisted chat sessions", "name" : "Chat sessions" }, { "description" : "The signed-in user's connected calendar accounts", "name" : "Calendar" }, { "description" : "Captured query scopes: frozen result sets referenced in later queries as (x:`$name`)", "name" : "KG Scopes" }, { "description" : "What your agents did, with a receipt for every decision", "name" : "Agent runs" }, { "description" : "Adopt handlers in your own world", "name" : "Handlers" }, { "description" : "Tips and hints for users", "name" : "Hints" }, { "description" : "Signal ingestion and backfill control", "name" : "Signals" }, { "description" : "The signed-in user's own display name, home location, and voice preferences", "name" : "Profile" }, { "description" : "Installed agent skills for the authenticated user", "name" : "Skills" }, { "description" : "Invoke named lenses and views headlessly; identity from the authenticated principal.", "name" : "Headless Invocation" }, { "description" : "Admin: run persisted virtual-join enrichment on demand", "name" : "Enrichment" }, { "description" : "Learn a connected source as a realm: detect, curate, probe, promote", "name" : "Learning" }, { "description" : "Receive and process webhook events from external systems", "name" : "Webhooks" }, { "description" : "Realm runtime metrics and logs", "name" : "Realm observability" }, { "description" : "The signal types this world actually receives", "name" : "Signals" }, { "description" : "Recent activity from this appliance's own log", "name" : "Diagnostics" }, { "description" : "Fictional records, marked and removable", "name" : "Sample data" }, { "description" : "What this server is built from", "name" : "About" }, { "description" : "Work the appliance is doing", "name" : "Activity" }, { "description" : "Admin: start, watch and cancel slow resumable materializations of expensive queries", "name" : "KG Fills" }, { "description" : "Record facts directly into the caller's memory, bypassing LLM extraction", "name" : "Memory" }, { "description" : "Admin: write annotations onto graph nodes via a dry-run, frozen plan, apply/undo cycle", "name" : "KG Annotations" }, { "description" : "Author, inspect and schedule the authenticated user's TypeScript event handlers (admin)", "name" : "Handlers" }, { "description" : "Generate, execute, monitor and cancel scoped knowledge-graph queries, and invoke saved views", "name" : "Virtual Cypher" }, { "description" : "What your agents ask you to approve", "name" : "Requests" } ] }