> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/api-reference/automations.md).

# Automations

Create and configure automations, revisions, schedules, triggers, and connections.

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}

> Get Automation

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}":{"get":{"summary":"Get Automation","operationId":"GetAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"show_deleted","description":"If true, the request will return the automation even if it has been soft-deleted.\nDeleted automations will have the `delete_time` field populated.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Automations"]}}}}
```

## Delete Automation

> DeleteAutomation soft deletes an automation from the system. The automation is purged sometime after\
> it has been deleted.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}":{"delete":{"summary":"Delete Automation","description":"DeleteAutomation soft deletes an automation from the system. The automation is purged sometime after\nit has been deleted.","operationId":"DeleteAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"force","description":"If set to true, any child resources (such as revisions) will also be deleted.\nIf set to false and the automation has child resources, the delete will fail.\nPer AIP-135, this field is required for resources with children.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Automations"]}}}}
```

## Update Automation

> UpdateAutomation modifies an existing automation with new code, artifacts, or dependencies.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}":{"patch":{"summary":"Update Automation","description":"UpdateAutomation modifies an existing automation with new code, artifacts, or dependencies.","operationId":"UpdateAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"update_mask","description":"For partial updates:\nIf specified, only fields specified in the field mask are updated.\nOtherwise, all fields are updated.\nFields are relative to the Automation message.","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonv1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"title":"Automation to update and new values for the automation.","required":["display_name"]}}},"description":"Automation to update and new values for the automation.","required":true},"tags":["Automations"]}}}}
```

## Query Automation

> This custom method allows explicit selection of which version stage to retrieve:\
> \- AUTOMATION\_STAGE\_DRAFT: Returns the latest draft version\
> \- AUTOMATION\_STAGE\_PUBLISHED: Returns the latest published version

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:query":{"get":{"summary":"Query Automation","description":"This custom method allows explicit selection of which version stage to retrieve:\n- AUTOMATION_STAGE_DRAFT: Returns the latest draft version\n- AUTOMATION_STAGE_PUBLISHED: Returns the latest published version","operationId":"QueryAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"The publication stage of the automation to retrieve.\nDetermines which version of the automation to return:\n- AUTOMATION_STAGE_DRAFT: Returns the latest draft version\n- AUTOMATION_STAGE_PUBLISHED: Returns the latest published version\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":true,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}}],"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/revisions/{revision\_id}

> Get Automation Revision

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationRevision":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation revision.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision}\nThe revision ID is the semantic version string (e.g., \"0.1\", \"1.0\", \"2.0\")."},"snapshot":{"$ref":"#/components/schemas/v1Automation"},"create_time":{"type":"string","format":"date-time","description":"Timestamp when this revision was created.","readOnly":true},"alternate_ids":{"type":"array","items":{"type":"string"},"description":"Other revision IDs that reference the same snapshot (e.g., \"latest\").\nPer AIP-162, this allows aliases for revisions.","readOnly":true},"input_diff":{"$ref":"#/components/schemas/v1AutomationInputDiff"}},"description":"AutomationRevision represents a historical revision (version) of an automation.\nRevisions are immutable snapshots created each time an automation is updated.\nPer AIP-162, this resource contains the complete state via a snapshot field."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"v1AutomationInputDiff":{"type":"object","properties":{"added":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in this revision but not in the previous revision.","readOnly":true},"removed":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in the previous revision but not in this revision.","readOnly":true},"modified":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in both revisions (matched by name) whose type differs.\nEach entry is the spec as of this (current) revision.","readOnly":true}},"description":"AutomationInputDiff describes how an automation's input specifications changed\nbetween two revisions. Only input specs (name and type) are compared; default\ninput values are not, since changing a default value does not create a new revision."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions/{revision_id}":{"get":{"summary":"Get Automation Revision","operationId":"GetAutomationRevision","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationRevision"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/revisions

> List Automation Revisions

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationRevisionsResponse":{"type":"object","properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationRevision"},"description":"The list of automation revisions for the current page.\nRevisions are ordered in reverse chronological order (newest first)."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"ListAutomationRevisionsResponse returns a page of automation revisions and pagination information."},"v1AutomationRevision":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation revision.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision}\nThe revision ID is the semantic version string (e.g., \"0.1\", \"1.0\", \"2.0\")."},"snapshot":{"$ref":"#/components/schemas/v1Automation"},"create_time":{"type":"string","format":"date-time","description":"Timestamp when this revision was created.","readOnly":true},"alternate_ids":{"type":"array","items":{"type":"string"},"description":"Other revision IDs that reference the same snapshot (e.g., \"latest\").\nPer AIP-162, this allows aliases for revisions.","readOnly":true},"input_diff":{"$ref":"#/components/schemas/v1AutomationInputDiff"}},"description":"AutomationRevision represents a historical revision (version) of an automation.\nRevisions are immutable snapshots created each time an automation is updated.\nPer AIP-162, this resource contains the complete state via a snapshot field."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"v1AutomationInputDiff":{"type":"object","properties":{"added":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in this revision but not in the previous revision.","readOnly":true},"removed":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in the previous revision but not in this revision.","readOnly":true},"modified":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in both revisions (matched by name) whose type differs.\nEach entry is the spec as of this (current) revision.","readOnly":true}},"description":"AutomationInputDiff describes how an automation's input specifications changed\nbetween two revisions. Only input specs (name and type) are compared; default\ninput values are not, since changing a default value does not create a new revision."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions":{"get":{"summary":"List Automation Revisions","operationId":"ListAutomationRevisions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationRevisionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of revisions to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, at most 50 revisions will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomationRevisions` call.\nProvide this to retrieve the subsequent page of results.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n  - `stage`: The automation revision stage (e.g., DRAFT, PUBLISHED)\n\nExample filters:\n  - `stage = \"DRAFT\"` - Returns only draft revisions\n  - `stage = \"PUBLISHED\"` - Returns only published revisions\n\nIf not specified or passed null, all revisions will be returned for that automation.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations

> List Automations

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationsResponse":{"type":"object","properties":{"automations":{"type":"array","items":{"$ref":"#/components/schemas/v1Automation"},"description":"The list of automations for the current page.\nMay be empty if no automations match the request criteria."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"ListAutomationsResponse returns a page of automations and pagination information."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations":{"get":{"summary":"List Automations","operationId":"ListAutomations","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of automations to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, at most 10 automations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nIf negative, an INVALID_ARGUMENT error will be returned.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomations` call.\nProvide this to retrieve the subsequent page of results.\nWhen paginating, all other parameters provided to `ListAutomations` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"show_deleted","description":"Filter to show/hide deleted automations. Deleted automations will be hidden by default.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n  - `state`: The automation state (e.g., DRAFT, PUBLISHED)\n  - `labels`: Automations carrying the label (case-insensitive match)\n\nExample filters:\n  - `state = \"PUBLISHED\"`\n  - `labels:\"finance\"`\n  - `labels:\"finance\" OR labels:\"ap\"` (carries any of the labels)\n  - `labels:\"finance\" AND labels:\"ap\"` (carries all of the labels)","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Reserved for future use. Comma-separated list of fields to order results by.\nPer AIP-132, this should be a string containing one or more field names,\neach optionally followed by \"asc\" or \"desc\" to specify sort direction.\n\nCurrently not implemented. Results are always ordered by `update_time desc`\n(most recently updated first).","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## Create Automation

> CreateAutomation creates a new automation with the provided name, code, and dependencies.\
> The created automation will have type DRAFT and can be updated before being published.\
> Returns the created automation with a unique ID and metadata.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations":{"post":{"summary":"Create Automation","description":"CreateAutomation creates a new automation with the provided name, code, and dependencies.\nThe created automation will have type DRAFT and can be updated before being published.\nReturns the created automation with a unique ID and metadata.","operationId":"CreateAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}},"description":"The automation to create","required":true},"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:invoke

> Invoke Automation

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1InvokeAutomationResponse":{"type":"object","properties":{"run_id":{"type":"string","description":"Unique identifier of the run created to execute the automation.\nUse this ID to track execution status and retrieve results."}},"description":"InvokeAutomationResponse returns the run ID for tracking the automation execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"InvokeAutomationBody":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input values to pass to the automation execution.\nKeys are input parameter names, values are the corresponding values."},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"enable_astral_on_rain":{"type":"boolean","description":"When true and the automation is Quill2 kind, enables Astral-on-Rain exception handling\nfor this invocation. Has no effect for non-Quill2 automations."},"idempotency_key":{"type":"string","description":"Client-supplied UUID4 idempotency token for InvokeAutomation.\nThreaded to Jeeves CreateRun as request_id so retries with the same key\nreturn the existing run instead of spawning a duplicate."}},"description":"InvokeAutomationRequest contains the automation ID and inputs needed to execute an automation.","required":["stage"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:invoke":{"post":{"summary":"Invoke Automation","operationId":"InvokeAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1InvokeAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## List Default Inputs History

> Results are returned in reverse chronological order (newest first).\
> Optionally filter by stage (DRAFT or PUBLISHED).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListDefaultInputsHistoryResponse":{"type":"object","properties":{"default_inputs_history_entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DefaultInputsHistoryEntry"},"description":"The history entries, ordered newest first."},"next_page_token":{"type":"string","description":"Token for retrieving the next page. Empty if no more results."}},"description":"ListDefaultInputsHistoryResponse contains a paginated list of default input history entries."},"v1DefaultInputsHistoryEntry":{"type":"object","properties":{"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The default inputs snapshot at the time of this change.","readOnly":true},"change_time":{"type":"string","format":"date-time","description":"When this change was made.","readOnly":true},"change_actor":{"type":"string","description":"User ID of the person who made this change.","readOnly":true}},"description":"DefaultInputsHistoryEntry represents a single default input change event."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:listDefaultInputsHistory":{"get":{"summary":"List Default Inputs History","description":"Results are returned in reverse chronological order (newest first).\nOptionally filter by stage (DRAFT or PUBLISHED).","operationId":"ListDefaultInputsHistory","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListDefaultInputsHistoryResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"Maximum number of entries to return. Defaults to 50 if not specified.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Page token for pagination, from a previous ListDefaultInputsHistoryResponse.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations:countConnectionUsage

> Count Connection Usage

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountConnectionUsageResponse":{"type":"object","properties":{"connection_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionAutomationCount"},"description":"List of connection IDs with their corresponding automation counts.\nThe order matches the order of connection_ids in the request."}},"description":"CountConnectionUsageResponse returns automation counts for each requested connection ID."},"v1ConnectionAutomationCount":{"type":"object","properties":{"connection_id":{"type":"string","description":"The connection ID being counted."},"count":{"type":"integer","format":"int32","description":"The number of automations that use this connection.\nIncludes both DRAFT and PUBLISHED automations by default."}},"description":"ConnectionAutomationCount represents the count of automations using a specific connection."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"CountConnectionUsageBody":{"type":"object","properties":{"connection_ids":{"type":"array","items":{"type":"string"},"description":"List of connection IDs to count automation usage for.\nEach connection ID will have a corresponding entry in the response."}},"description":"CountConnectionUsageRequest specifies connection IDs to count automation usage for.","required":["connection_ids"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:countConnectionUsage":{"post":{"summary":"Count Connection Usage","operationId":"CountConnectionUsage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountConnectionUsageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountConnectionUsageBody"}}},"required":true},"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations:traceConnectionUsage

> Trace Connection Usage

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1TraceConnectionUsageResponse":{"type":"object","properties":{"automations":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationConnectionUsage"},"description":"List of automations that use the specified connection, with their stages."}},"description":"TraceConnectionUsageResponse returns automations that use the specified connection."},"v1AutomationConnectionUsage":{"type":"object","properties":{"automation_id":{"type":"string","description":"The automation ID that uses the connection.\nThis is the automation ID portion only (e.g., the {automation} part of the resource name)."},"stages":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationStage"},"description":"The stages in which this automation uses the connection.\nCan include AUTOMATION_STAGE_DRAFT, AUTOMATION_STAGE_PUBLISHED, or both."}},"description":"AutomationConnectionUsage represents an automation that uses a specific connection,\nalong with the stages (DRAFT, PUBLISHED, or both) where the connection is used."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"TraceConnectionUsageBody":{"type":"object","properties":{"connection_id":{"type":"string","description":"The connection ID to trace usage for.\nReturns all automations that use this connection."}},"description":"TraceConnectionUsageRequest specifies which connection to trace usage for.","required":["connection_id"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:traceConnectionUsage":{"post":{"summary":"Trace Connection Usage","operationId":"TraceConnectionUsage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1TraceConnectionUsageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceConnectionUsageBody"}}},"required":true},"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:extractCodeConnections

> Extract Automation Code Connections

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ExtractAutomationCodeConnectionsResponse":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"List of connections found in the automation's SPy code.\nIncludes both placeholder connections (without connection_id) and concrete connections (with connection_id).","readOnly":true}},"description":"ExtractAutomationCodeConnectionsResponse returns connection information from the automation's SPy code."},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:extractCodeConnections":{"get":{"summary":"Extract Automation Code Connections","operationId":"ExtractAutomationCodeConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ExtractAutomationCodeConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n  - `stage`: The automation stage to extract connections from (e.g., DRAFT, PUBLISHED)\n\nExample filters:\n  - `stage = \"DRAFT\"`\n  - `stage = \"PUBLISHED\"`","in":"query","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## Upgrade Automation Connections

> Multiple connections can be upgraded in a single atomic operation. All upgrades succeed\
> together or all fail together. The automation version is incremented once for all upgrades.\
> \
> This operation only works on draft automations. To upgrade connections in a published\
> automation, first use ForkPublishedAutomation to create a draft, then call this method.\
> \
> Per AIP-136, this is a custom method using the :upgradeConnections suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UpgradeAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"UpgradeAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"UpgradeAutomationConnectionsBody":{"type":"object","properties":{"upgrades":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionReplacement"},"description":"List of connections to upgrade. All upgrades are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all upgrades.\n\nEach old_connection_id must be unique within the list. If the same old_connection_id\nappears multiple times, the request will fail with INVALID_ARGUMENT."}},"description":"UpgradeAutomationConnectionsRequest specifies which connections to upgrade in a draft automation.","required":["upgrades"]},"v1ConnectionReplacement":{"type":"object","properties":{"old_connection_id":{"type":"string","description":"The current connection ID to replace.\nThis connection ID must exist in the automation."},"new_connection_id":{"type":"string","title":"The new connection ID to use as replacement.\nThis connection must:\n- Exist in the workspace\n- Have the same book_name as the old connection\n- Have the same book_version as the old connection"},"connection_alias":{"type":"string","description":"The alias of the connection to use as replacement.\nThis alias must be unique within the automation."}},"description":"ConnectionReplacement specifies replacing one connection ID with another.","required":["old_connection_id","new_connection_id","connection_alias"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:upgradeConnections":{"post":{"summary":"Upgrade Automation Connections","description":"Multiple connections can be upgraded in a single atomic operation. All upgrades succeed\ntogether or all fail together. The automation version is incremented once for all upgrades.\n\nThis operation only works on draft automations. To upgrade connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :upgradeConnections suffix.","operationId":"UpgradeAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UpgradeAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Switch Automation Connections

> Multiple connections can be switched in a single atomic operation. All switches succeed\
> together or all fail together. The automation version is incremented once for all switches.\
> \
> This operation only works on draft automations. To switch connections in a published\
> automation, first use ForkPublishedAutomation to create a draft, then call this method.\
> \
> Per AIP-136, this is a custom method using the :switchConnections suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1SwitchAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"SwitchAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SwitchAutomationConnectionsBody":{"type":"object","properties":{"switches":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionReplacement"},"description":"List of connections to switch. All switches are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all switches.\n\nEach old_connection_id must be unique within the list. If the same old_connection_id\nappears multiple times, the request will fail with INVALID_ARGUMENT."}},"description":"SwitchAutomationConnectionsRequest specifies which connections to switch in a draft automation.","required":["switches"]},"v1ConnectionReplacement":{"type":"object","properties":{"old_connection_id":{"type":"string","description":"The current connection ID to replace.\nThis connection ID must exist in the automation."},"new_connection_id":{"type":"string","title":"The new connection ID to use as replacement.\nThis connection must:\n- Exist in the workspace\n- Have the same book_name as the old connection\n- Have the same book_version as the old connection"},"connection_alias":{"type":"string","description":"The alias of the connection to use as replacement.\nThis alias must be unique within the automation."}},"description":"ConnectionReplacement specifies replacing one connection ID with another.","required":["old_connection_id","new_connection_id","connection_alias"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:switchConnections":{"post":{"summary":"Switch Automation Connections","description":"Multiple connections can be switched in a single atomic operation. All switches succeed\ntogether or all fail together. The automation version is incremented once for all switches.\n\nThis operation only works on draft automations. To switch connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :switchConnections suffix.","operationId":"SwitchAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1SwitchAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwitchAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Remove Automation Connections

> Multiple connections can be removed in a single atomic operation. All removals succeed\
> together or all fail together. The automation version is incremented once for all removals.\
> \
> This operation only works on draft automations. To remove connections in a published\
> automation, first use ForkPublishedAutomation to create a draft, then call this method.\
> \
> Per AIP-136, this is a custom method using the :removeConnections suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1RemoveAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"RemoveAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"RemoveAutomationConnectionsBody":{"type":"object","properties":{"removals":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionRemoval"},"description":"List of connections to remove. All removals are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all removals.\n\nEach connection (identified by connection_id and connection_alias) must be unique\nwithin the list. If the same connection appears multiple times, the request will\nfail with INVALID_ARGUMENT.\n\nFor each connection, the corresponding entry in automation.connections will be removed\nand code references will be replaced with placeholders (kognitos.connection_name.{book})."}},"description":"RemoveAutomationConnectionsRequest specifies which connections to remove from a draft automation.","required":["removals"]},"v1ConnectionRemoval":{"type":"object","properties":{"connection_id":{"type":"string","description":"The connection ID to remove.\nThis connection ID must exist in the automation."},"connection_alias":{"type":"string","description":"The alias of the connection to remove.\nThis alias must match the connection being removed."}},"description":"ConnectionRemoval specifies a connection to remove from an automation.","required":["connection_id","connection_alias"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:removeConnections":{"post":{"summary":"Remove Automation Connections","description":"Multiple connections can be removed in a single atomic operation. All removals succeed\ntogether or all fail together. The automation version is incremented once for all removals.\n\nThis operation only works on draft automations. To remove connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :removeConnections suffix.","operationId":"RemoveAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1RemoveAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Add Automation Connections

> Multiple connections can be added in a single atomic operation. All additions succeed\
> together or all fail together. The automation version is incremented once for all additions.\
> \
> This operation only works on draft automations. To add connections to a published\
> automation, first use ForkPublishedAutomation to create a draft, then call this method.\
> \
> Per AIP-136, this is a custom method using the :addConnections suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AddAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"AddAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AddAutomationConnectionsBody":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"List of connections to add. All additions are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all additions.\n\nEach connection must be unique within the list. If duplicate connections appear,\nthe request will fail with INVALID_ARGUMENT."}},"description":"AddAutomationConnectionsRequest specifies which connections to add to a draft automation.","required":["connections"]},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:addConnections":{"post":{"summary":"Add Automation Connections","description":"Multiple connections can be added in a single atomic operation. All additions succeed\ntogether or all fail together. The automation version is incremented once for all additions.\n\nThis operation only works on draft automations. To add connections to a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :addConnections suffix.","operationId":"AddAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AddAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/visualization

> Get Automation Visualization

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationVisualization":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the visualization.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/visualization"},"graph":{"$ref":"#/components/schemas/v1FlowGraph"},"automation_version":{"type":"string","description":"The semantic version of the automation this visualization represents.\nFormat: \"major.0\" (e.g., \"1.0\", \"2.0\", \"3.0\") - always a published version.\nThis corresponds to the automation's published version at the time of generation.","readOnly":true},"state":{"$ref":"#/components/schemas/v1VisualizationState"},"error_message":{"type":"string","description":"Error message describing why generation failed.\nOnly populated when state is VISUALIZATION_STATE_FAILED.","readOnly":true}},"description":"AutomationVisualization represents a visual representation of an automation's execution flow.\nVisualizations are generated for published automation versions and stored as configurations\nfor rendering in the UI. This is a singleton resource - each automation has exactly one visualization\nrepresenting its latest published version."},"v1FlowGraph":{"type":"object","properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/v1FlowNode"},"description":"List of nodes representing steps in the automation flow."},"edges":{"type":"array","items":{"$ref":"#/components/schemas/v1FlowEdge"},"description":"List of edges representing connections between nodes."}},"description":"FlowGraph represents the execution flow of an automation as a directed graph.\nThe graph consists of nodes (representing steps) and edges (representing transitions)."},"v1FlowNode":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this node within the graph."},"label":{"type":"string","description":"Human-readable label describing this step."},"type":{"$ref":"#/components/schemas/v1FlowNodeType"}},"description":"FlowNode represents a single step or decision point in the automation flow."},"v1FlowNodeType":{"type":"string","enum":["FLOW_NODE_TYPE_UNSPECIFIED","FLOW_NODE_TYPE_START","FLOW_NODE_TYPE_END","FLOW_NODE_TYPE_PROCESS","FLOW_NODE_TYPE_DECISION","FLOW_NODE_TYPE_INPUT","FLOW_NODE_TYPE_OUTPUT"],"default":"FLOW_NODE_TYPE_UNSPECIFIED","description":"FlowNodeType defines the different types of nodes in an automation flow.\n\n - FLOW_NODE_TYPE_UNSPECIFIED: Unspecified node type.\n - FLOW_NODE_TYPE_START: Start node - represents the beginning of the flow.\n - FLOW_NODE_TYPE_END: End node - represents the end of the flow.\n - FLOW_NODE_TYPE_PROCESS: Process node - represents a processing step.\n - FLOW_NODE_TYPE_DECISION: Decision node - represents a branching point (if-else conditions).\n - FLOW_NODE_TYPE_INPUT: Input node - represents an input action.\n - FLOW_NODE_TYPE_OUTPUT: Output node - represents an output action."},"v1FlowEdge":{"type":"object","properties":{"source":{"type":"string","description":"ID of the source node where the edge originates."},"target":{"type":"string","description":"ID of the target node where the edge points."},"condition":{"type":"string","description":"Optional condition label for the edge (e.g., \"Yes\", \"No\" for decision branches)."}},"description":"FlowEdge represents a directed connection between two nodes."},"v1VisualizationState":{"type":"string","enum":["VISUALIZATION_STATE_UNSPECIFIED","VISUALIZATION_STATE_PENDING","VISUALIZATION_STATE_COMPLETED","VISUALIZATION_STATE_FAILED"],"default":"VISUALIZATION_STATE_UNSPECIFIED","description":"VisualizationState indicates the current state of visualization generation.\n\n - VISUALIZATION_STATE_UNSPECIFIED: Unspecified state.\n - VISUALIZATION_STATE_PENDING: Visualization generation is in progress.\n - VISUALIZATION_STATE_COMPLETED: Visualization generation completed successfully.\n - VISUALIZATION_STATE_FAILED: Visualization generation failed."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/visualization":{"get":{"summary":"Get Automation Visualization","operationId":"GetAutomationVisualization","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationVisualization"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule

> Get Automation Schedule

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."},"window_start":{"$ref":"#/components/schemas/typeTimeOfDay"},"window_end":{"$ref":"#/components/schemas/typeTimeOfDay"}},"description":"Time window for querying insights."},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"get":{"summary":"Get Automation Schedule","operationId":"GetAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule

> Create Automation Schedule

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."},"window_start":{"$ref":"#/components/schemas/typeTimeOfDay"},"window_end":{"$ref":"#/components/schemas/typeTimeOfDay"}},"description":"Time window for querying insights."},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"post":{"summary":"Create Automation Schedule","operationId":"CreateAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}},"description":"The schedule to create.","required":true},"tags":["Automations"]}}}}
```

## DELETE /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule

> Delete Automation Schedule

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"delete":{"summary":"Delete Automation Schedule","operationId":"DeleteAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## PATCH /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule

> Update Automation Schedule

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."},"window_start":{"$ref":"#/components/schemas/typeTimeOfDay"},"window_end":{"$ref":"#/components/schemas/typeTimeOfDay"}},"description":"Time window for querying insights."},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"patch":{"summary":"Update Automation Schedule","operationId":"UpdateAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"title":"The schedule to update.","required":["config"]}}},"description":"The schedule to update.","required":true},"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:disableAutomationSchedule

> Disable Automation Schedule

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DisableAutomationScheduleResponse":{"type":"object","properties":{"schedule":{"$ref":"#/components/schemas/v1AutomationSchedule"}},"description":"DisableAutomationScheduleResponse contains the disabled schedule."},"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."},"window_start":{"$ref":"#/components/schemas/typeTimeOfDay"},"window_end":{"$ref":"#/components/schemas/typeTimeOfDay"}},"description":"Time window for querying insights."},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"DisableAutomationScheduleBody":{"type":"object","description":"DisableAutomationScheduleRequest is the request to disable a schedule (pause without deleting)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:disableAutomationSchedule":{"post":{"summary":"Disable Automation Schedule","operationId":"DisableAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DisableAutomationScheduleResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableAutomationScheduleBody"}}},"required":true},"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:enableAutomationSchedule

> Enable Automation Schedule

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1EnableAutomationScheduleResponse":{"type":"object","properties":{"schedule":{"$ref":"#/components/schemas/v1AutomationSchedule"}},"description":"EnableAutomationScheduleResponse contains the enabled schedule."},"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."},"window_start":{"$ref":"#/components/schemas/typeTimeOfDay"},"window_end":{"$ref":"#/components/schemas/typeTimeOfDay"}},"description":"Time window for querying insights."},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"EnableAutomationScheduleBody":{"type":"object","description":"EnableAutomationScheduleRequest is the request to enable a previously disabled schedule."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:enableAutomationSchedule":{"post":{"summary":"Enable Automation Schedule","operationId":"EnableAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1EnableAutomationScheduleResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableAutomationScheduleBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Delete Workspace Connection

> This API validates that the connection is not in use by any published\
> automations before deletion. If only draft automations use the connection,\
> deletion proceeds and returns the list of affected automations.\
> \
> The affected draft automations will have unresolved connection references\
> after deletion. They can still be edited but cannot be published until\
> new connections are configured.\
> \
> Errors:\
> \- FAILED\_PRECONDITION: Connection is in use by one or more published automations.\
> &#x20; The error details include DeleteConnectionBlockedError with blocking automations.\
> \- NOT\_FOUND: Connection not found in the workspace.\
> \- INTERNAL: Failed to communicate with the connection storage service.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DeleteWorkspaceConnectionResponse":{"type":"object","properties":{"affected_automations":{"type":"array","items":{"$ref":"#/components/schemas/v1AffectedAutomation"},"description":"List of draft automations that were affected by the deletion.\nThese automations have connection references that are now unresolved.\nEmpty if no draft automations were using the connection.","readOnly":true}},"description":"DeleteWorkspaceConnectionResponse returns information about affected automations."},"v1AffectedAutomation":{"type":"object","properties":{"automation_id":{"type":"string","description":"The automation ID (the {automation} segment of the resource name).","readOnly":true},"display_name":{"type":"string","description":"The human-readable display name of the automation.","readOnly":true}},"description":"AffectedAutomation describes a draft automation affected by connection deletion."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:deleteConnection":{"delete":{"summary":"Delete Workspace Connection","description":"This API validates that the connection is not in use by any published\nautomations before deletion. If only draft automations use the connection,\ndeletion proceeds and returns the list of affected automations.\n\nThe affected draft automations will have unresolved connection references\nafter deletion. They can still be edited but cannot be published until\nnew connections are configured.\n\nErrors:\n- FAILED_PRECONDITION: Connection is in use by one or more published automations.\n  The error details include DeleteConnectionBlockedError with blocking automations.\n- NOT_FOUND: Connection not found in the workspace.\n- INTERNAL: Failed to communicate with the connection storage service.","operationId":"DeleteWorkspaceConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DeleteWorkspaceConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","description":"The connection ID to delete.","in":"query","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/triggers

> List Automation Triggers

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationTriggersResponse":{"type":"object","properties":{"automation_triggers":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationTrigger"},"description":"List of triggers that are active for the specified automation."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"Response containing the list of active triggers for an automation."},"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers":{"get":{"summary":"List Automation Triggers","operationId":"ListAutomationTriggers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationTriggersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of triggers to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, a default page size will be used.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomationTriggers` call.\nProvide this to retrieve the subsequent page of results.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"A filter expression to apply to the list of triggers.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/triggers

> Create Automation Trigger

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers":{"post":{"summary":"Create Automation Trigger","operationId":"CreateAutomationTrigger","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationTrigger"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"The automation stage to create the trigger for.\nOptional; if unset, the service applies its default stage behavior.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":false,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationTrigger"}}},"description":"The trigger phase configuration to store.","required":true},"tags":["Automations"]}}}}
```

## Export Agent

> Exports an agent (optionally a specific version) together with the\
> automations it references as a single ZIP bundle. Uploads the bundle to file\
> storage and returns a \~1-hour presigned download URL. SPy code files inside\
> the bundled automations are encrypted at rest within the bundle.\
> \
> Only the latest published revision of each referenced automation is\
> bundled; drafts are never exported. The agent's attached automations and\
> connections are read from the agent's effective tool catalog — its enabled\
> \`automations\` and \`connection\` tool sources — so an automation that merely\
> lives in the same workspace is not included.\
> \
> When the agent has no automations attached, the export still succeeds: the\
> result is an agent-only bundle and a warning is returned in \`warnings\`. The\
> export deliberately does NOT fall back to bundling every published\
> automation in the workspace.\
> \
> Export is tolerant of incomplete source state: an automation that\
> references a connection no longer present in the workspace is still\
> bundled, with that connection alias omitted and a warning returned in\
> \`warnings\`. A missing connection does not fail the export — the alias is\
> reported again by ValidateAgentImport at the destination so it can be wired\
> up there.\
> \
> Fails with FAILED\_PRECONDITION if the encryption key is not configured.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ExportAgentResponse":{"type":"object","properties":{"zip_uri":{"type":"string","description":"Presigned download URL for the exported ZIP bundle (valid ~1 hour).\nThe caller can download the bundle directly from this URL.","readOnly":true},"expire_time":{"type":"string","format":"date-time","description":"Expiration time of the download URL (1 hour from creation).","readOnly":true},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal warnings produced while building the bundle. A warning does not\ninvalidate the bundle — it records something the destination operator needs\nto know before or after importing it. Typical cases: an automation\nreferenced a connection that no longer exists in the source workspace (that\nalias is omitted from the bundle and must be wired up after import), or the\nagent declared no automations at all, making the bundle agent-only.\n\nThese warnings are also stored in the bundle itself, so ImportAgent and\nValidateAgentImport surface them at the destination.","readOnly":true},"automation_names":{"type":"array","items":{"type":"string"},"title":"Resource names of the automations actually bundled, as selected from the\nagent's effective tool catalog. Empty for an agent-only bundle.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"agent_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1AgentConnection"},"description":"Book connections the exported agent has attached to itself through its\n`connection` tool sources. These belong to the agent, not to any bundled\nautomation, and must already exist in the destination workspace for the\nimported agent to be able to use them.","readOnly":true}},"description":"Response message for ExportAgent."},"v1AgentConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"The id of the connection the agent's tool source points at (e.g. \"idp-jxnvp\").","readOnly":true},"book_name":{"type":"string","description":"The book name that provides this connection type (e.g. \"google-sheets\").","readOnly":true},"book_version":{"type":"string","description":"The book version the connection is pinned to, when the tool source reports one.","readOnly":true},"display_name":{"type":"string","description":"The connection display name as it appears in the agent's source workspace.","readOnly":true}},"description":"A book connection attached directly to an agent through one of its\n`connection` tool sources. This describes the agent's own tool wiring, not any\nautomation it calls: it is read from the agent's effective tool catalog and is\nunrelated to MissingConnection, which describes connection aliases referenced\nby an automation's phase code."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AgentImportExportServiceExportAgentBody":{"type":"object","properties":{"agent_version":{"type":"string","description":"The agent version to export. When empty, the latest version is exported."}},"description":"Request message for ExportAgent."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agentBundles/{agent_id}:export":{"post":{"summary":"Export Agent","description":"Exports an agent (optionally a specific version) together with the\nautomations it references as a single ZIP bundle. Uploads the bundle to file\nstorage and returns a ~1-hour presigned download URL. SPy code files inside\nthe bundled automations are encrypted at rest within the bundle.\n\nOnly the latest published revision of each referenced automation is\nbundled; drafts are never exported. The agent's attached automations and\nconnections are read from the agent's effective tool catalog — its enabled\n`automations` and `connection` tool sources — so an automation that merely\nlives in the same workspace is not included.\n\nWhen the agent has no automations attached, the export still succeeds: the\nresult is an agent-only bundle and a warning is returned in `warnings`. The\nexport deliberately does NOT fall back to bundling every published\nautomation in the workspace.\n\nExport is tolerant of incomplete source state: an automation that\nreferences a connection no longer present in the workspace is still\nbundled, with that connection alias omitted and a warning returned in\n`warnings`. A missing connection does not fail the export — the alias is\nreported again by ValidateAgentImport at the destination so it can be wired\nup there.\n\nFails with FAILED_PRECONDITION if the encryption key is not configured.","operationId":"ExportWorkspaceAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ExportAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentImportExportServiceExportAgentBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Validate Agent Import

> Validates an agent that may have been created via import. Reports whether\
> the agent was imported and, if so, what is still missing across its bundled\
> automations before they can run: connections that have no match in the\
> workspace and trigger kinds that are not yet configured. Read-only; makes\
> no changes.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ValidateAgentImportResponse":{"type":"object","properties":{"is_imported_agent":{"type":"boolean","description":"Whether this agent was created via import.\nWhen false, the missing_* fields are empty and no validation was performed.","readOnly":true},"missing_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1MissingConnection"},"description":"Connections referenced by the *bundled automations'* phase code that have no\nmatch in the workspace. Reuses the automation import MissingConnection type;\nthe phase field is prefixed with the owning automation id. These are code\naliases inside the automations — see agent_connections for the connections\nthe agent itself is wired to.","readOnly":true},"missing_trigger_kinds":{"type":"array","items":{"$ref":"#/components/schemas/v1PhaseSubType"},"description":"The kinds of triggers (e.g. Email, Schedule, Webhook) required by the\nbundled automations' pre-phases that are not yet configured in the workspace.","readOnly":true},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal warnings captured at import time (e.g. from the agent service).","readOnly":true},"agent_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1AgentConnection"},"description":"Book connections attached to the *agent itself* through its `connection`\ntool sources, reported whether or not they resolve in this workspace. A\nseparate concern from missing_connections: these come from the agent's tool\ncatalog rather than from any automation's phase code.","readOnly":true}},"description":"Response message for ValidateAgentImport."},"v1MissingConnection":{"type":"object","properties":{"phase":{"type":"string","description":"The phase that requires this connection (\"main\", \"post\", or \"pre[0]\", \"pre[1]\", etc.).","readOnly":true},"alias":{"type":"string","description":"The connection alias used in the phase code.","readOnly":true},"book_name":{"type":"string","description":"The book name that provides this connection type (e.g. \"google-sheets\").","readOnly":true},"book_version":{"type":"string","description":"The book version referenced by the automation.","readOnly":true},"source_connection_display_name":{"type":"string","description":"The connection display name as referenced by the imported automation.","readOnly":true}},"description":"A connection referenced by an imported automation that is missing from the workspace."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"v1AgentConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"The id of the connection the agent's tool source points at (e.g. \"idp-jxnvp\").","readOnly":true},"book_name":{"type":"string","description":"The book name that provides this connection type (e.g. \"google-sheets\").","readOnly":true},"book_version":{"type":"string","description":"The book version the connection is pinned to, when the tool source reports one.","readOnly":true},"display_name":{"type":"string","description":"The connection display name as it appears in the agent's source workspace.","readOnly":true}},"description":"A book connection attached directly to an agent through one of its\n`connection` tool sources. This describes the agent's own tool wiring, not any\nautomation it calls: it is read from the agent's effective tool catalog and is\nunrelated to MissingConnection, which describes connection aliases referenced\nby an automation's phase code."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AgentImportExportServiceValidateAgentImportBody":{"type":"object","description":"Request message for ValidateAgentImport."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agentBundles/{agent_id}:validateImport":{"post":{"summary":"Validate Agent Import","description":"Validates an agent that may have been created via import. Reports whether\nthe agent was imported and, if so, what is still missing across its bundled\nautomations before they can run: connections that have no match in the\nworkspace and trigger kinds that are not yet configured. Read-only; makes\nno changes.","operationId":"ValidateAgentImport","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ValidateAgentImportResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentImportExportServiceValidateAgentImportBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Import Agent

> Imports an exported agent ZIP bundle into a workspace. Every bundled\
> automation is recreated as a new draft 0.1, the newly created identifiers\
> are rewritten into the agent template YAML, and the agent is then created in\
> the target workspace. The operation is all-or-nothing: if any resource\
> fails to be created, everything created so far is rolled back.\
> \
> Import always CREATES; it never updates an existing agent. The imported\
> agent is assigned a freshly minted id, distinct from the id it had in the\
> source workspace, and each bundled sub-agent is likewise created under a\
> fresh id. Consequently:\
> &#x20; \- the returned \`agent\` never names a pre-existing agent, and importing a\
> &#x20;   bundle can never overwrite, version over, or delete one;\
> &#x20; \- importing the same bundle twice — including back into the workspace it\
> &#x20;   was exported from — yields two independent agents;\
> &#x20; \- the source agent id is retained only as provenance, and is reported by\
> &#x20;   ValidateAgentImport rather than reused as an identifier.\
> Callers that want to replace an agent should delete it and import again.\
> \
> Fails with FAILED\_PRECONDITION if the encryption key is not configured.\
> Fails with INVALID\_ARGUMENT if the bundle is malformed or decryption fails.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ImportAgentResponse":{"type":"object","properties":{"agent":{"type":"string","title":"The resource name of the newly created agent.\nFormat: organizations/{organization}/workspaces/{workspace}/agents/{agent}","readOnly":true},"automation_names":{"type":"array","items":{"type":"string"},"title":"Resource names of the newly created draft automations bundled with the agent.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal warnings produced while applying the agent (e.g. from the agent\nservice), such as unchanged sub-agents or advisory notices.","readOnly":true},"agent_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1AgentConnection"},"description":"Book connections the newly imported agent expects on itself, carried over\nfrom the exported agent's `connection` tool sources. Import does not create\nthese connections; wire them up in the target workspace right afterwards.","readOnly":true}},"description":"Response message for ImportAgent."},"v1AgentConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"The id of the connection the agent's tool source points at (e.g. \"idp-jxnvp\").","readOnly":true},"book_name":{"type":"string","description":"The book name that provides this connection type (e.g. \"google-sheets\").","readOnly":true},"book_version":{"type":"string","description":"The book version the connection is pinned to, when the tool source reports one.","readOnly":true},"display_name":{"type":"string","description":"The connection display name as it appears in the agent's source workspace.","readOnly":true}},"description":"A book connection attached directly to an agent through one of its\n`connection` tool sources. This describes the agent's own tool wiring, not any\nautomation it calls: it is read from the agent's effective tool catalog and is\nunrelated to MissingConnection, which describes connection aliases referenced\nby an automation's phase code."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AgentImportExportServiceImportAgentBody":{"type":"object","properties":{"zip_resource":{"type":"string","description":"Bishop resource name of the ZIP bundle to import.\nFormat: organizations/{organization}/workspaces/{workspace}/files/{name}\nThe caller obtains this by uploading the exported bundle to Bishop in the\ntarget workspace; it is not a download URL."}},"description":"Request message for ImportAgent.","required":["zip_resource"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agentBundles:import":{"post":{"summary":"Import Agent","description":"Imports an exported agent ZIP bundle into a workspace. Every bundled\nautomation is recreated as a new draft 0.1, the newly created identifiers\nare rewritten into the agent template YAML, and the agent is then created in\nthe target workspace. The operation is all-or-nothing: if any resource\nfails to be created, everything created so far is rolled back.\n\nImport always CREATES; it never updates an existing agent. The imported\nagent is assigned a freshly minted id, distinct from the id it had in the\nsource workspace, and each bundled sub-agent is likewise created under a\nfresh id. Consequently:\n  - the returned `agent` never names a pre-existing agent, and importing a\n    bundle can never overwrite, version over, or delete one;\n  - importing the same bundle twice — including back into the workspace it\n    was exported from — yields two independent agents;\n  - the source agent id is retained only as provenance, and is reported by\n    ValidateAgentImport rather than reused as an identifier.\nCallers that want to replace an agent should delete it and import again.\n\nFails with FAILED_PRECONDITION if the encryption key is not configured.\nFails with INVALID_ARGUMENT if the bundle is malformed or decryption fails.","operationId":"ImportWorkspaceAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ImportAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentImportExportServiceImportAgentBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Delete Draft Automation

> DeleteDraftAutomation deletes draft versions of an automation.\
> This endpoint specifically targets draft automations and will fail if the automation is not in DRAFT state.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/drafts":{"delete":{"summary":"Delete Draft Automation","description":"DeleteDraftAutomation deletes draft versions of an automation.\nThis endpoint specifically targets draft automations and will fail if the automation is not in DRAFT state.","operationId":"DeleteDraftAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"force","description":"If set to true, any child resources will also be deleted.\nIf set to false and the automation has child resources, the delete will fail.\nPer AIP-135, this field is required for resources with children.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Automations"]}}}}
```

## Promote Params To Code

> PromoteParamsToCode writes tuned params back into the automation's draft SPy\
> source at their value-slot locations (inline literal or a constant's\
> definition), committing a new draft version. The adopt-the-winner step.\
> Per AIP-136, a custom method (:promoteParamsToCode).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1PromoteParamsToCodeResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"Response for PromoteParamsToCode."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServicePromoteParamsToCodeBody":{"type":"object","properties":{"params":{"type":"array","items":{"$ref":"#/components/schemas/v1ParamEdit"},"description":"Edits to apply to the draft source (paths are self-addressing per value slot)."},"etag":{"type":"string","description":"Optimistic-concurrency tag (AIP-154) from the IdentifyStepValueSlots /\nBuildStepHarness response the edits were derived from. When set, the promote\nis rejected with ABORTED if the draft has since changed; when empty, the\nedits are applied to the current draft (last-writer-wins)."}},"description":"Request for PromoteParamsToCode. Always targets the DRAFT stage.","required":["params"]},"v1ParamEdit":{"type":"object","properties":{"path":{"type":"string","description":"A value-slot path from IdentifyStepValueSlots."},"value":{"description":"The new literal value."}},"description":"A single param edit: set the literal at `path` to `value`.","required":["path","value"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/promotedParams":{"post":{"summary":"Promote Params To Code","description":"PromoteParamsToCode writes tuned params back into the automation's draft SPy\nsource at their value-slot locations (inline literal or a constant's\ndefinition), committing a new draft version. The adopt-the-winner step.\nPer AIP-136, a custom method (:promoteParamsToCode).","operationId":"PromoteParamsToCode","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1PromoteParamsToCodeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServicePromoteParamsToCodeBody"}}},"required":true},"tags":["Automations"]}}}}
```

## List Automation Revision Summaries

> ListAutomationRevisionSummaries returns a paginated list of lightweight revision\
> summaries for a specific automation. It mirrors ListAutomationRevisions but omits\
> the heavy \`code\` (SPy) and \`description\` fields from each revision's snapshot,\
> keeping responses small enough for version-history list views and avoiding oversized\
> responses that exceed the API gateway's gRPC-JSON transcoding buffer.\
> Revisions are returned in reverse chronological order (newest first) by default.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationRevisionSummariesResponse":{"type":"object","properties":{"automation_revision_summaries":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationRevisionSummary"},"description":"The list of automation revision summaries for the current page.\nRevisions are ordered in reverse chronological order (newest first)."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"ListAutomationRevisionSummariesResponse returns a page of automation revision\nsummaries and pagination information."},"v1AutomationRevisionSummary":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation revision.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision}\nThe revision ID is the semantic version string (e.g., \"0.1\", \"1.0\", \"2.0\").","readOnly":true},"snapshot":{"$ref":"#/components/schemas/v1Automation"},"create_time":{"type":"string","format":"date-time","description":"Timestamp when this revision was created.","readOnly":true},"alternate_ids":{"type":"array","items":{"type":"string"},"description":"Other revision IDs that reference the same snapshot (e.g., \"latest\").\nPer AIP-162, this allows aliases for revisions.","readOnly":true},"input_diff":{"$ref":"#/components/schemas/v1AutomationInputDiff"}},"description":"AutomationRevisionSummary is a lightweight projection of AutomationRevision for\nversion-history list views. It mirrors AutomationRevision field-for-field, but its\nsnapshot intentionally omits the heavy `code` (SPy) field and the `description`\nfield; every other automation field is populated exactly as in\nAutomationRevision.snapshot. Omitting these keeps listing many revisions cheap and\nprevents oversized responses that fail gRPC-JSON transcoding at the API gateway.\n\nThis is a projection/view of the AutomationRevision resource, not a resource itself,\nso it deliberately carries no google.api.resource annotation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"v1AutomationInputDiff":{"type":"object","properties":{"added":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in this revision but not in the previous revision.","readOnly":true},"removed":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in the previous revision but not in this revision.","readOnly":true},"modified":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"Input specs present in both revisions (matched by name) whose type differs.\nEach entry is the spec as of this (current) revision.","readOnly":true}},"description":"AutomationInputDiff describes how an automation's input specifications changed\nbetween two revisions. Only input specs (name and type) are compared; default\ninput values are not, since changing a default value does not create a new revision."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions:listSummaries":{"get":{"summary":"List Automation Revision Summaries","description":"ListAutomationRevisionSummaries returns a paginated list of lightweight revision\nsummaries for a specific automation. It mirrors ListAutomationRevisions but omits\nthe heavy `code` (SPy) and `description` fields from each revision's snapshot,\nkeeping responses small enough for version-history list views and avoiding oversized\nresponses that exceed the API gateway's gRPC-JSON transcoding buffer.\nRevisions are returned in reverse chronological order (newest first) by default.","operationId":"ListAutomationRevisionSummaries","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationRevisionSummariesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of revision summaries to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, at most 50 revision summaries will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomationRevisionSummaries` call.\nProvide this to retrieve the subsequent page of results.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n  - `stage`: The automation revision stage (e.g., DRAFT, PUBLISHED)\n\nExample filters:\n  - `stage = \"DRAFT\"` - Returns only draft revisions\n  - `stage = \"PUBLISHED\"` - Returns only published revisions\n\nIf not specified or passed null, all revision summaries will be returned for that automation.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## Inspect Step Config

> InspectStepConfig reads the current candidate/tuned overlay for an automation\
> stage. Read-only. Per AIP-136, a custom method (:inspectStepConfig) — not a\
> standard AIP-131 Get: there is no standalone StepConfig resource, and the\
> overlay is addressed by parent automation + stage.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1InspectStepConfigResponse":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/v1StepConfig"}},"description":"Response for InspectStepConfig."},"v1StepConfig":{"type":"object","properties":{"automation":{"type":"string","title":"Parent automation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"values":{"type":"object","additionalProperties":{},"description":"Candidate/tuned values keyed by ValueSlot.path. google.protobuf.Value to\nmatch ValueSlot.value / ParamEdit.value (the promote path); grimoire converts\nto common.v1.Value when it emits BuildStepHarness.tunable_slots for a run."},"etag":{"type":"string","description":"Opaque version tag of the draft these values were set against (AIP-154);\nlets a caller detect the draft changed under an in-flight tuning session."}},"description":"The candidate/tuned value overlay for one automation stage — the durable store\nbehind uncommitted step testing. Not a resource (a small keyed overlay owned by\nthe automation), addressed by the parent automation + stage."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/stepConfig":{"get":{"summary":"Inspect Step Config","description":"InspectStepConfig reads the current candidate/tuned overlay for an automation\nstage. Read-only. Per AIP-136, a custom method (:inspectStepConfig) — not a\nstandard AIP-131 Get: there is no standalone StepConfig resource, and the\noverlay is addressed by parent automation + stage.","operationId":"InspectStepConfig","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1InspectStepConfigResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"Stage to read.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":true,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}}],"tags":["Automations"]}}}}
```

## Tune Step Config

> TuneStepConfig upserts candidate/tuned value-slot values for an automation's\
> DRAFT — the durable store behind uncommitted step testing. Keys are\
> ValueSlot.path (from IdentifyStepValueSlots). Values present are upserted; a\
> value of NullValue clears that key. These are applied at run time (via the\
> Jarvis arg-override, surfaced through BuildStepHarness.tunable\_slots) without\
> editing source; PromoteParamsToCode bakes the winner into code.\
> Per AIP-136, a custom method (:tuneStepConfig).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1TuneStepConfigResponse":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/v1StepConfig"}},"description":"Response for TuneStepConfig."},"v1StepConfig":{"type":"object","properties":{"automation":{"type":"string","title":"Parent automation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"values":{"type":"object","additionalProperties":{},"description":"Candidate/tuned values keyed by ValueSlot.path. google.protobuf.Value to\nmatch ValueSlot.value / ParamEdit.value (the promote path); grimoire converts\nto common.v1.Value when it emits BuildStepHarness.tunable_slots for a run."},"etag":{"type":"string","description":"Opaque version tag of the draft these values were set against (AIP-154);\nlets a caller detect the draft changed under an in-flight tuning session."}},"description":"The candidate/tuned value overlay for one automation stage — the durable store\nbehind uncommitted step testing. Not a resource (a small keyed overlay owned by\nthe automation), addressed by the parent automation + stage."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceTuneStepConfigBody":{"type":"object","properties":{"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"values":{"type":"object","additionalProperties":{},"description":"Slot values to upsert (ValueSlot.path → value). NullValue clears a key."},"replace":{"type":"boolean","description":"When true, replace the whole overlay with `values` (omitted keys are cleared)\nrather than merging. Default false = merge/upsert."},"etag":{"type":"string","description":"Optimistic concurrency: reject with ABORTED if the draft changed since this\netag (from IdentifyStepValueSlots / ReadStepConfig). Empty = last-writer-wins."}},"description":"Request for TuneStepConfig.","required":["stage","values"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/stepConfig":{"post":{"summary":"Tune Step Config","description":"TuneStepConfig upserts candidate/tuned value-slot values for an automation's\nDRAFT — the durable store behind uncommitted step testing. Keys are\nValueSlot.path (from IdentifyStepValueSlots). Values present are upserted; a\nvalue of NullValue clears that key. These are applied at run time (via the\nJarvis arg-override, surfaced through BuildStepHarness.tunable_slots) without\nediting source; PromoteParamsToCode bakes the winner into code.\nPer AIP-136, a custom method (:tuneStepConfig).","operationId":"TuneStepConfig","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1TuneStepConfigResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceTuneStepConfigBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Build Step Harness

> BuildStepHarness generates an "options-as-input" wrapper for a step so it can\
> be run live over multiple inputs (via alfred's step evals) without editing the\
> real automation: the chosen value slots become harness parameters. Read-only.\
> Per AIP-136, a custom method (:buildStepHarness).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BuildStepHarnessResponse":{"type":"object","properties":{"entry_point":{"type":"string","description":"The Jarvis entry-point function to invoke for the isolated single-step run."},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1HarnessInput"},"description":"Inputs the step run expects (from the manifest step args / recorded I/O)."},"tunable_slots":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueSlot"},"description":"The value slots exposed as runtime-tunable params for the run."},"is_mutating":{"type":"boolean","description":"Whether the target step performs a world-changing book call (manifest\nExternalCall.is_mutating) — so the caller can gate a live run."},"etag":{"type":"string","description":"Opaque version tag of the code the harness was built from (AIP-154)."}},"description":"Response for BuildStepHarness. The step runs in isolation via the Jarvis\nsingle-step entry point over recorded inputs (from Bishop); this describes\nthat run rather than synthesizing SPy."},"v1HarnessInput":{"type":"object","properties":{"name":{"type":"string","description":"Input parameter name."},"input_type":{"type":"string","description":"The input's SPy type."},"is_file":{"type":"boolean","description":"True if the input is a file to upload/reference."}},"description":"An input the generated harness expects.\n"},"v1ValueSlot":{"type":"object","properties":{"path":{"type":"string","description":"Stable address for this slot; also the PromoteParamsToCode edit key."},"value":{"description":"Current value (null for a computed slot)."},"slot_type":{"type":"string","description":"Widget/format hint: money/number/text/date/status/rule/bool/enum."},"label":{"type":"string","description":"Human-readable label (arg / field name)."},"editability":{"$ref":"#/components/schemas/ValueSlotEditability"},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"An editable value in a step, derived from the Jarvis CodeManifest (a step\narg / external-call CallArg). Step-testing primitive (with\nIdentifyStepValueSlots, BuildStepHarness, PromoteParamsToCode) — eval\nexecution + scoring live in Alfred."},"ValueSlotEditability":{"type":"string","enum":["EDITABILITY_UNSPECIFIED","EDITABILITY_LITERAL","EDITABILITY_COMPUTED"],"default":"EDITABILITY_UNSPECIFIED","description":"Whether this slot's value can be edited, mirroring the manifest CallArg\nsource classification.\n\n - EDITABILITY_UNSPECIFIED: Default; unset.\n - EDITABILITY_LITERAL: An inline literal — editable (PromoteParamsToCode).\n - EDITABILITY_COMPUTED: A computed value (variable/expression) — surfaced read-only."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/stepHarness":{"get":{"summary":"Build Step Harness","description":"BuildStepHarness generates an \"options-as-input\" wrapper for a step so it can\nbe run live over multiple inputs (via alfred's step evals) without editing the\nreal automation: the chosen value slots become harness parameters. Read-only.\nPer AIP-136, a custom method (:buildStepHarness).","operationId":"BuildStepHarness","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BuildStepHarnessResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"Which stage's code to wrap (DRAFT or PUBLISHED).\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":true,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}},{"name":"step","description":"The step's entry-point function name.","in":"query","required":true,"schema":{"type":"string"}},{"name":"slot_paths","description":"Value-slot paths to expose as tunable params. Empty = all editable slots.","in":"query","required":false,"explode":true,"schema":{"type":"array","items":{"type":"string"}}}],"tags":["Automations"]}}}}
```

## Delete Automation Trigger

> DeleteAutomationTrigger removes a trigger from an automation and tears down\
> its external (BDK) trigger instance. The trigger must exist for the given\
> stage. Returns the trigger as it existed immediately before removal.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DeleteAutomationTriggerResponse":{"type":"object","properties":{"automation_trigger":{"$ref":"#/components/schemas/v1AutomationTrigger"}},"description":"Response containing the deleted trigger."},"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers/{trigger_id}":{"delete":{"summary":"Delete Automation Trigger","description":"DeleteAutomationTrigger removes a trigger from an automation and tears down\nits external (BDK) trigger instance. The trigger must exist for the given\nstage. Returns the trigger as it existed immediately before removal.","operationId":"DeleteAutomationTrigger","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DeleteAutomationTriggerResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"trigger_id","description":"The external trigger ID to delete.\nThis ID uniquely identifies the trigger in the external system.\nThis field is populated from the URL path parameter.","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"The automation stage to delete the trigger from.\nMust be either AUTOMATION_STAGE_DRAFT or AUTOMATION_STAGE_PUBLISHED.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":true,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}}],"tags":["Automations"]}}}}
```

## Activate Trigger

> ActivateTrigger activates a trigger for an automation.\
> The trigger must exist and be in a deactivated state.\
> Returns the activated trigger configuration.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ActivateTriggerResponse":{"type":"object","properties":{"automation_trigger":{"$ref":"#/components/schemas/v1AutomationTrigger"}},"description":"Response containing the activated trigger."},"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationPhaseServiceActivateTriggerBody":{"type":"object","properties":{"stage":{"$ref":"#/components/schemas/v1AutomationStage"}},"description":"Request to activate a trigger for an automation.","required":["stage"]},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers/{trigger_id}:activate":{"post":{"summary":"Activate Trigger","description":"ActivateTrigger activates a trigger for an automation.\nThe trigger must exist and be in a deactivated state.\nReturns the activated trigger configuration.","operationId":"ActivateTrigger","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ActivateTriggerResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"trigger_id","description":"The external trigger ID to activate.\nThis ID uniquely identifies the trigger in the external system.\nThis field is populated from the URL path parameter.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPhaseServiceActivateTriggerBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Deactivate Trigger

> DeactivateTrigger deactivates a trigger for an automation.\
> The trigger must exist and be in an activated state.\
> Returns the deactivated trigger configuration.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DeactivateTriggerResponse":{"type":"object","properties":{"automation_trigger":{"$ref":"#/components/schemas/v1AutomationTrigger"}},"description":"Response containing the deactivated trigger."},"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationPhaseServiceDeactivateTriggerBody":{"type":"object","properties":{"stage":{"$ref":"#/components/schemas/v1AutomationStage"}},"description":"Request to deactivate a trigger for an automation.","required":["stage"]},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers/{trigger_id}:deactivate":{"post":{"summary":"Deactivate Trigger","description":"DeactivateTrigger deactivates a trigger for an automation.\nThe trigger must exist and be in an activated state.\nReturns the deactivated trigger configuration.","operationId":"DeactivateTrigger","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DeactivateTriggerResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"trigger_id","description":"The external trigger ID to deactivate.\nThis ID uniquely identifies the trigger in the external system.\nThis field is populated from the URL path parameter.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPhaseServiceDeactivateTriggerBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Identify Step Value Slots

> IdentifyStepValueSlots returns the editable value slots of a step — the IDP\
> prompt/options (inline literals or nested options fields) and any constants\
> the step consumes (even when defined elsewhere in the code) — for step-level\
> tuning. Read-only. Per AIP-136, a custom method (:identifyStepValueSlots).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1IdentifyStepValueSlotsResponse":{"type":"object","properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueSlot"},"description":"The step's editable value slots."},"etag":{"type":"string","description":"Opaque version tag of the code these slots were read from (AIP-154). Pass it\nback to PromoteParamsToCode so a promotion based on a stale read is rejected."}},"description":"Response for IdentifyStepValueSlots."},"v1ValueSlot":{"type":"object","properties":{"path":{"type":"string","description":"Stable address for this slot; also the PromoteParamsToCode edit key."},"value":{"description":"Current value (null for a computed slot)."},"slot_type":{"type":"string","description":"Widget/format hint: money/number/text/date/status/rule/bool/enum."},"label":{"type":"string","description":"Human-readable label (arg / field name)."},"editability":{"$ref":"#/components/schemas/ValueSlotEditability"},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"An editable value in a step, derived from the Jarvis CodeManifest (a step\narg / external-call CallArg). Step-testing primitive (with\nIdentifyStepValueSlots, BuildStepHarness, PromoteParamsToCode) — eval\nexecution + scoring live in Alfred."},"ValueSlotEditability":{"type":"string","enum":["EDITABILITY_UNSPECIFIED","EDITABILITY_LITERAL","EDITABILITY_COMPUTED"],"default":"EDITABILITY_UNSPECIFIED","description":"Whether this slot's value can be edited, mirroring the manifest CallArg\nsource classification.\n\n - EDITABILITY_UNSPECIFIED: Default; unset.\n - EDITABILITY_LITERAL: An inline literal — editable (PromoteParamsToCode).\n - EDITABILITY_COMPUTED: A computed value (variable/expression) — surfaced read-only."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/valueSlots":{"get":{"summary":"Identify Step Value Slots","description":"IdentifyStepValueSlots returns the editable value slots of a step — the IDP\nprompt/options (inline literals or nested options fields) and any constants\nthe step consumes (even when defined elsewhere in the code) — for step-level\ntuning. Read-only. Per AIP-136, a custom method (:identifyStepValueSlots).","operationId":"IdentifyStepValueSlots","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1IdentifyStepValueSlotsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"Which stage's code to analyze (DRAFT or PUBLISHED).\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":true,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}},{"name":"step","description":"The step's entry-point function name (from CodeManifest.Step.entry_function.name).","in":"query","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```

## Activate Automation

> ActivateAutomation reactivates a previously deactivated automation.\
> This allows the automation to execute new runs again.\
> Returns FAILED\_PRECONDITION if:\
> &#x20; \- The automation has no published version\
> &#x20; \- The automation is already active\
> \
> Per AIP-136, this is a custom method using the :activate suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ActivateAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"ActivateAutomationResponse returns the activated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceActivateAutomationBody":{"type":"object","description":"ActivateAutomationRequest specifies which automation to activate."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:activate":{"post":{"summary":"Activate Automation","description":"ActivateAutomation reactivates a previously deactivated automation.\nThis allows the automation to execute new runs again.\nReturns FAILED_PRECONDITION if:\n  - The automation has no published version\n  - The automation is already active\n\nPer AIP-136, this is a custom method using the :activate suffix.","operationId":"ActivateAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ActivateAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceActivateAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Deactivate Automation

> DeactivateAutomation stops an automation from executing new runs.\
> All events (scheduled, manual, webhook) will be logged but not executed.\
> The automation can be reactivated at any time using ActivateAutomation.\
> Returns FAILED\_PRECONDITION if:\
> &#x20; \- The automation has no published version\
> &#x20; \- The automation is already deactivated\
> \
> Per AIP-136, this is a custom method using the :deactivate suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DeactivateAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"DeactivateAutomationResponse returns the deactivated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceDeactivateAutomationBody":{"type":"object","description":"DeactivateAutomationRequest specifies which automation to deactivate."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:deactivate":{"post":{"summary":"Deactivate Automation","description":"DeactivateAutomation stops an automation from executing new runs.\nAll events (scheduled, manual, webhook) will be logged but not executed.\nThe automation can be reactivated at any time using ActivateAutomation.\nReturns FAILED_PRECONDITION if:\n  - The automation has no published version\n  - The automation is already deactivated\n\nPer AIP-136, this is a custom method using the :deactivate suffix.","operationId":"DeactivateAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DeactivateAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceDeactivateAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Duplicate Automation

> DuplicateAutomation creates a new automation by copying an existing one within the same workspace.\
> The duplicated automation is a new, independent entity with its own identity, ownership, and version history.\
> Only the specified stage (draft or published) is copied, not the full version history.\
> All phases (MAIN, POST, and PRE if they exist) are copied.\
> Connections are copied by reference within the same workspace.\
> If display\_name is provided in the request, the duplicated automation uses that name;\
> otherwise the server generates a default name based on the source automation's display name.\
> Per AIP-136, this is a custom method using the :duplicate suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DuplicateAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"DuplicateAutomationResponse returns the newly created duplicated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceDuplicateAutomationBody":{"type":"object","properties":{"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"display_name":{"type":"string","description":"Optional display name for the new duplicated automation.\nIf not provided, the backend will generate a default name\n(e.g., \"Copy of <original display name>\")."}},"description":"DuplicateAutomationRequest specifies which automation to duplicate and which stage to copy.","required":["stage"]},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:duplicate":{"post":{"summary":"Duplicate Automation","description":"DuplicateAutomation creates a new automation by copying an existing one within the same workspace.\nThe duplicated automation is a new, independent entity with its own identity, ownership, and version history.\nOnly the specified stage (draft or published) is copied, not the full version history.\nAll phases (MAIN, POST, and PRE if they exist) are copied.\nConnections are copied by reference within the same workspace.\nIf display_name is provided in the request, the duplicated automation uses that name;\notherwise the server generates a default name based on the source automation's display name.\nPer AIP-136, this is a custom method using the :duplicate suffix.","operationId":"DuplicateAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DuplicateAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceDuplicateAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Export Automation

> Exports a specific revision of an automation as a ZIP bundle.\
> Uploads the bundle to file storage and returns a 1-hour presigned download URL.\
> The bundle contains all automation phases, connections metadata, trigger metadata,\
> and provenance information. SPy code files are encrypted at rest within the bundle.\
> Fails with FAILED\_PRECONDITION if the encryption key is not configured.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ExportAutomationResponse":{"type":"object","properties":{"zip_uri":{"type":"string","description":"Presigned download URL for the exported ZIP bundle (valid ~1 hour).\nThe caller can download the bundle directly from this URL.","readOnly":true},"expire_time":{"type":"string","format":"date-time","description":"Expiration time of the download URL (1 hour from creation).","readOnly":true}},"description":"Response message for ExportAutomation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationImportExportServiceExportAutomationBody":{"type":"object","properties":{"revision_id":{"type":"string","description":"The revision ID to export (e.g. \"1.0\", \"0.3\")."}},"description":"Request message for ExportAutomation.","required":["revision_id"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:export":{"post":{"summary":"Export Automation","description":"Exports a specific revision of an automation as a ZIP bundle.\nUploads the bundle to file storage and returns a 1-hour presigned download URL.\nThe bundle contains all automation phases, connections metadata, trigger metadata,\nand provenance information. SPy code files are encrypted at rest within the bundle.\nFails with FAILED_PRECONDITION if the encryption key is not configured.","operationId":"ExportAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ExportAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationImportExportServiceExportAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Fork Published Automation

> ForkPublishedAutomation creates a draft from the last published version of an automation.\
> This effectively resets the draft state to match the published state.\
> Per AIP-136, this is a custom method using the :fork suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ForkPublishedAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"ForkPublishedAutomationResponse returns the updated automation with the forked draft state."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceForkPublishedAutomationBody":{"type":"object","description":"ForkPublishedAutomationRequest specifies which automation to fork."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:fork":{"post":{"summary":"Fork Published Automation","description":"ForkPublishedAutomation creates a draft from the last published version of an automation.\nThis effectively resets the draft state to match the published state.\nPer AIP-136, this is a custom method using the :fork suffix.","operationId":"ForkPublishedAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ForkPublishedAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceForkPublishedAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Move Automation

> Moves a specific revision of an automation directly into another workspace\
> (in the same organization or a different one) within the same environment.\
> Unlike export/import, this is a direct intra-platform copy and does not produce\
> or consume a ZIP bundle. The source automation is left intact; a new draft\
> automation is created in the target workspace. Connections and triggers are\
> matched automatically in the target workspace.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1MoveAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"Response message for MoveAutomation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationImportExportServiceMoveAutomationBody":{"type":"object","properties":{"destination_workspace":{"type":"string","title":"The target workspace to move the automation into. May be in the same\norganization or a different one. Must be in the same environment as the source.\nFormat: organizations/{organization}/workspaces/{workspace}"},"revision_id":{"type":"string","description":"The revision ID to move (e.g. \"12.0\", \"0.3\")."}},"description":"Request message for MoveAutomation.","required":["destination_workspace","revision_id"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:move":{"post":{"summary":"Move Automation","description":"Moves a specific revision of an automation directly into another workspace\n(in the same organization or a different one) within the same environment.\nUnlike export/import, this is a direct intra-platform copy and does not produce\nor consume a ZIP bundle. The source automation is left intact; a new draft\nautomation is created in the target workspace. Connections and triggers are\nmatched automatically in the target workspace.","operationId":"MoveAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1MoveAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationImportExportServiceMoveAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Publish Automation

> PublishAutomation publishes an automation with the provided credentials.\
> Creates a new immutable AutomationRevision and updates latest\_published\_version.\
> Per AIP-136, this is a custom method using the :publish suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1PublishAutomationResponse":{"type":"object","properties":{"published_version":{"type":"string","title":"The semantic version of the newly published automation (format: major.minor).\nThis corresponds to the AutomationRevision that was created.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true}},"description":"PublishAutomationResponse returns the published semantic version."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServicePublishAutomationBody":{"type":"object","properties":{"resolved_placeholder_test_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"Connections with resolved placeholder test credentials.\nThese connections have test credentials that have been resolved to actual credentials."}},"description":"PublishAutomationRequest contains the automation and credentials needed to publish.","required":["resolved_placeholder_test_credentials"]},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:publish":{"post":{"summary":"Publish Automation","description":"PublishAutomation publishes an automation with the provided credentials.\nCreates a new immutable AutomationRevision and updates latest_published_version.\nPer AIP-136, this is a custom method using the :publish suffix.","operationId":"PublishAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1PublishAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServicePublishAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Rename Automation

> RenameAutomation changes the display name of an automation without modifying\
> the automation content (code, connections, artifacts). This operation does not\
> increment the automation version since only metadata is changed.\
> \
> Per AIP-136, this is a custom method using the :rename suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceRenameAutomationBody":{"type":"object","properties":{"display_name":{"type":"string","description":"The new display name for the automation."}},"description":"RenameAutomationRequest contains the new display name for an automation.\nThis operation does not affect the automation version.","required":["display_name"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:rename":{"post":{"summary":"Rename Automation","description":"RenameAutomation changes the display name of an automation without modifying\nthe automation content (code, connections, artifacts). This operation does not\nincrement the automation version since only metadata is changed.\n\nPer AIP-136, this is a custom method using the :rename suffix.","operationId":"RenameAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceRenameAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Restore Automation

> RestoreAutomation restores an automation to a previous version.\
> This copies the snapshot from the specified revision into the current draft,\
> and populates restore\_time, restore\_version, and restore\_user\_id fields.\
> Per AIP-136, this is a custom method using the :restore suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1RestoreAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"RestoreAutomationResponse returns the restored automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceRestoreAutomationBody":{"type":"object","properties":{"revision_id":{"type":"string","description":"The revision ID (semantic version) to restore to (e.g., \"1.0\", \"2.0\").\nThis must be a valid published version that exists in the automation's revision history."}},"description":"RestoreAutomationRequest specifies which automation to restore and to which version.","required":["revision_id"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:restore":{"post":{"summary":"Restore Automation","description":"RestoreAutomation restores an automation to a previous version.\nThis copies the snapshot from the specified revision into the current draft,\nand populates restore_time, restore_version, and restore_user_id fields.\nPer AIP-136, this is a custom method using the :restore suffix.","operationId":"RestoreAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1RestoreAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceRestoreAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Set Automation Default Inputs

> SetAutomationDefaultInputs sets or updates default input values for an automation.\
> Default inputs are used to pre-populate values for manual runs and fill missing\
> inputs for trigger-based invocations. This operation updates the latest version\
> of the specified stage in-place without creating a new version.\
> \
> The provided default\_inputs are merged with existing defaults:\
> \- Keys present in the request overwrite existing defaults\
> \- Keys with null\_value remove the default for that input\
> \- Existing keys not present in the request are preserved\
> \
> Per AIP-136, this is a custom method using the :setDefaultInputs suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceSetAutomationDefaultInputsBody":{"type":"object","properties":{"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonv1Value"},"description":"Default input values to set.\nKeys are input parameter names (matching AutomationInputSpec.name).\nValues are the default values for those inputs.\nMerged with existing defaults: provided keys overwrite, null_value entries remove the key."},"stage":{"$ref":"#/components/schemas/v1AutomationStage"}},"description":"SetAutomationDefaultInputsRequest contains the default input values to set for an automation.","required":["default_inputs","stage"]},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:setDefaultInputs":{"post":{"summary":"Set Automation Default Inputs","description":"SetAutomationDefaultInputs sets or updates default input values for an automation.\nDefault inputs are used to pre-populate values for manual runs and fill missing\ninputs for trigger-based invocations. This operation updates the latest version\nof the specified stage in-place without creating a new version.\n\nThe provided default_inputs are merged with existing defaults:\n- Keys present in the request overwrite existing defaults\n- Keys with null_value remove the default for that input\n- Existing keys not present in the request are preserved\n\nPer AIP-136, this is a custom method using the :setDefaultInputs suffix.","operationId":"SetAutomationDefaultInputs","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceSetAutomationDefaultInputsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Set Automation Labels

> SetAutomationLabels replaces the full label set of an automation.\
> Labels not in the given list are removed and new ones are added.\
> An empty list removes all labels. Like RenameAutomation, this only\
> changes metadata and does not create a new automation version.\
> \
> Labels are matched case-insensitively. A label already used in the\
> workspace under a different casing is stored in that existing spelling.\
> \
> Per AIP-136, this is a custom method using the :setLabels suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceSetAutomationLabelsBody":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"string"},"description":"The full desired label set. At most 20 labels, each 1 to 255\ncharacters after trimming. Empty removes all labels."}},"description":"SetAutomationLabelsRequest contains the full label set for an automation."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:setLabels":{"post":{"summary":"Set Automation Labels","description":"SetAutomationLabels replaces the full label set of an automation.\nLabels not in the given list are removed and new ones are added.\nAn empty list removes all labels. Like RenameAutomation, this only\nchanges metadata and does not create a new automation version.\n\nLabels are matched case-insensitively. A label already used in the\nworkspace under a different casing is stored in that existing spelling.\n\nPer AIP-136, this is a custom method using the :setLabels suffix.","operationId":"SetAutomationLabels","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceSetAutomationLabelsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Set Marked Outputs

> SetMarkedOutputs sets a single marked output key for an automation.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1SetMarkedOutputsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"Response containing the automation after setting a marked output."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationPhaseServiceSetMarkedOutputsBody":{"type":"object","properties":{"marked_output":{"type":"string","description":"The marked output key to add."}},"description":"Request to set a single marked output key for an automation.","required":["marked_output"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:setMarkedOutputs":{"post":{"summary":"Set Marked Outputs","description":"SetMarkedOutputs sets a single marked output key for an automation.","operationId":"SetMarkedOutputs","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1SetMarkedOutputsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPhaseServiceSetMarkedOutputsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Unset Marked Output

> UnsetMarkedOutput removes a single marked output key from an automation.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UnsetMarkedOutputResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"Response containing the automation after unsetting a marked output."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationPhaseServiceUnsetMarkedOutputBody":{"type":"object","properties":{"marked_output":{"type":"string","description":"The marked output key to remove."}},"description":"Request to unset (remove) a single marked output key from an automation.","required":["marked_output"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:unsetMarkedOutput":{"post":{"summary":"Unset Marked Output","description":"UnsetMarkedOutput removes a single marked output key from an automation.","operationId":"UnsetMarkedOutput","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UnsetMarkedOutputResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationPhaseServiceUnsetMarkedOutputBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Upgrade Automation Book Connection Version

> UpgradeAutomationBookConnectionVersion upgrades all connections of a specific book\
> within a draft automation to a specified target version. Every connection whose\
> book matches will be transitioned to new\_book\_version in a single atomic update.\
> The target version does not need to be the latest — any higher version is valid.\
> \
> This operation only works on draft automations. To upgrade connections in a published\
> automation, first use ForkPublishedAutomation to create a draft, then call this method.\
> \
> Per AIP-136, this is a custom method using the :upgradeBookConnectionVersion suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UpgradeAutomationBookConnectionVersionResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"},"upgraded_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"Connection info for every connection that was newly upgraded on this\nautomation. Each entry reflects the book, version, connection id/alias,\nand phase of an upgraded connection slot.","readOnly":true}},"description":"UpgradeAutomationBookConnectionVersionResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceUpgradeAutomationBookConnectionVersionBody":{"type":"object","properties":{"book":{"type":"string","description":"The book whose connections should be upgraded.\nMust match the book field of CredentialInfo for connections to be selected."},"new_book_version":{"type":"string","description":"The target book version to upgrade to.\nIf not specified, defaults to the latest available version of the book.\nIf specified, must be higher than the current version of the connections being upgraded."}},"description":"UpgradeAutomationBookConnectionVersionRequest specifies the book version transition to apply\nacross all matching connections in a draft automation.","required":["book"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:upgradeBookConnectionVersion":{"post":{"summary":"Upgrade Automation Book Connection Version","description":"UpgradeAutomationBookConnectionVersion upgrades all connections of a specific book\nwithin a draft automation to a specified target version. Every connection whose\nbook matches will be transitioned to new_book_version in a single atomic update.\nThe target version does not need to be the latest — any higher version is valid.\n\nThis operation only works on draft automations. To upgrade connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :upgradeBookConnectionVersion suffix.","operationId":"UpgradeAutomationBookConnectionVersion","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UpgradeAutomationBookConnectionVersionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceUpgradeAutomationBookConnectionVersionBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Validate Automation Import

> Validates an automation that may have been created via import. Reports whether\
> the automation was imported and, if so, what is still missing before it can run:\
> connections that have no match in the workspace and trigger kinds that are not\
> yet configured for the automation's pre-phases. Read-only; makes no changes.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ValidateAutomationImportResponse":{"type":"object","properties":{"is_imported_automation":{"type":"boolean","description":"Whether this automation was created via import.\nWhen false, the missing_* fields are empty and no validation was performed.","readOnly":true},"missing_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1MissingConnection"},"description":"Connections referenced by the automation that have no match in the workspace.","readOnly":true},"missing_trigger_kinds":{"type":"array","items":{"$ref":"#/components/schemas/v1PhaseSubType"},"description":"The kinds of triggers (e.g. Email, Schedule, Webhook) required by the\nautomation's pre-phases that are not yet configured in the workspace.","readOnly":true}},"description":"Response message for ValidateAutomationImport."},"v1MissingConnection":{"type":"object","properties":{"phase":{"type":"string","description":"The phase that requires this connection (\"main\", \"post\", or \"pre[0]\", \"pre[1]\", etc.).","readOnly":true},"alias":{"type":"string","description":"The connection alias used in the phase code.","readOnly":true},"book_name":{"type":"string","description":"The book name that provides this connection type (e.g. \"google-sheets\").","readOnly":true},"book_version":{"type":"string","description":"The book version referenced by the automation.","readOnly":true},"source_connection_display_name":{"type":"string","description":"The connection display name as referenced by the imported automation.","readOnly":true}},"description":"A connection referenced by an imported automation that is missing from the workspace."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationImportExportServiceValidateAutomationImportBody":{"type":"object","description":"Request message for ValidateAutomationImport."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:validateImport":{"post":{"summary":"Validate Automation Import","description":"Validates an automation that may have been created via import. Reports whether\nthe automation was imported and, if so, what is still missing before it can run:\nconnections that have no match in the workspace and trigger kinds that are not\nyet configured for the automation's pre-phases. Read-only; makes no changes.","operationId":"ValidateAutomationImport","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ValidateAutomationImportResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationImportExportServiceValidateAutomationImportBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Validate Automation Publish

> ValidateAutomationPublish checks if an automation is ready to be published.\
> Returns information about missing credentials needed for publish.\
> Per AIP-136, this is a custom method using the :validatePublish suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ValidateAutomationPublishResponse":{"type":"object","properties":{"missing_prod_creds":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"Connections missing only production credentials.\nThese connections have test credentials but need production credentials to publish.","readOnly":true},"missing_test_and_prod_creds":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"Connections missing both test and production credentials.\nThese connections need both credential types to be provided.","readOnly":true}},"description":"ValidateAutomationPublishResponse returns validation results for publishing."},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceValidateAutomationPublishBody":{"type":"object","description":"ValidateAutomationPublishRequest validates if an automation can be published."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:validatePublish":{"post":{"summary":"Validate Automation Publish","description":"ValidateAutomationPublish checks if an automation is ready to be published.\nReturns information about missing credentials needed for publish.\nPer AIP-136, this is a custom method using the :validatePublish suffix.","operationId":"ValidateAutomationPublish","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ValidateAutomationPublishResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceValidateAutomationPublishBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Bulk Upgrade Automation Book Connections

> BulkUpgradeAutomationBookConnections upgrades all connections of a specific book\
> across multiple draft automations in a single request. The book is resolved from\
> the provided connection\_id — every connection slot in each automation that belongs\
> to that book is replaced with the new connection, regardless of alias name.\
> \
> Each automation is processed independently: a failure on one automation does not\
> block the remaining automations. The automation version is incremented once per\
> successfully upgraded automation.\
> \
> This operation only works on draft automations. To upgrade connections in a published\
> automation, first use ForkPublishedAutomation to create a draft, then call this method.\
> \
> Per AIP-136, this is a custom method using the :bulkUpgradeBookConnections suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BulkUpgradeAutomationBookConnectionsResponse":{"type":"object","properties":{"successful_automation_ids":{"type":"array","items":{"type":"string"},"description":"IDs of automations whose book connections were successfully upgraded.","readOnly":true},"failed_automations":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationBookConnectionUpgradeFailure"},"description":"Automations that could not be upgraded, each with a reason for the failure.\nAn automation appears here if it does not exist, is not a draft, does not\ncontain any connection for the resolved book, or encounters any other error.","readOnly":true},"upgraded_connections":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"Connection info for every connection that was newly upgraded across all\nsuccessfully-upgraded automations, flattened into a single list. Each entry\nreflects the book, version, connection id/alias, and phase of an upgraded\nconnection slot.","readOnly":true}},"description":"BulkUpgradeAutomationBookConnectionsResponse is the response for BulkUpgradeAutomationBookConnections."},"v1AutomationBookConnectionUpgradeFailure":{"type":"object","properties":{"automation_id":{"type":"string","description":"The ID of the automation that failed to upgrade.","readOnly":true},"error_message":{"type":"string","description":"Human-readable description of why the upgrade failed for this automation.\nOther automations in the same request are not affected by this failure.","readOnly":true}},"description":"AutomationBookConnectionUpgradeFailure describes a single automation that could not\nbe upgraded during a BulkUpgradeAutomationBookConnections call."},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationServiceBulkUpgradeAutomationBookConnectionsBody":{"type":"object","properties":{"automation_ids":{"type":"array","items":{"type":"string"},"description":"IDs of the draft automations in which to upgrade book connections.\nEach entry is an automation nano ID (not a full resource name).\nAll specified automations must be drafts; published automations must be forked\nvia ForkPublishedAutomation before being passed here."},"connection_id":{"type":"string","description":"The ID of the new connection to apply. The book is resolved from this connection —\nevery connection slot in each automation that belongs to the same book will be\nupgraded to use this connection_id, regardless of the connection's alias name."},"new_book_version":{"type":"string","description":"The target book version to upgrade to.\nIf not specified, defaults to the latest available version of the book.\nIf specified, must be higher than the current version of the connections being upgraded."}},"description":"BulkUpgradeAutomationBookConnectionsRequest is the request for BulkUpgradeAutomationBookConnections.","required":["automation_ids","connection_id"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:bulkUpgradeBookConnections":{"post":{"summary":"Bulk Upgrade Automation Book Connections","description":"BulkUpgradeAutomationBookConnections upgrades all connections of a specific book\nacross multiple draft automations in a single request. The book is resolved from\nthe provided connection_id — every connection slot in each automation that belongs\nto that book is replaced with the new connection, regardless of alias name.\n\nEach automation is processed independently: a failure on one automation does not\nblock the remaining automations. The automation version is incremented once per\nsuccessfully upgraded automation.\n\nThis operation only works on draft automations. To upgrade connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :bulkUpgradeBookConnections suffix.","operationId":"BulkUpgradeAutomationBookConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BulkUpgradeAutomationBookConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationServiceBulkUpgradeAutomationBookConnectionsBody"}}},"required":true},"tags":["Automations"]}}}}
```

## Import Automation

> Imports an exported automation ZIP bundle into a workspace as a new draft 0.1.\
> Connections and triggers are re-wired via caller-supplied mappings.\
> If display\_name conflicts with an existing automation in the target workspace,\
> the name is automatically resolved by prefixing with "1 - ", "2 - ", etc.\
> Fails with FAILED\_PRECONDITION if the encryption key is not configured.\
> Fails with INVALID\_ARGUMENT if the bundle is malformed or decryption fails.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ImportAutomationResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"Response message for ImportAutomation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."},"code_manifest":{"$ref":"#/components/schemas/v1CodeManifest"},"collections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1CollectionRef"},"description":"Collections required by this automation, resolved to concrete references.\nMaps each collection slug to its CollectionRef (mirrors connections)."},"config":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ConfigValue"},"description":"Business-tunable configuration values for this automation, keyed by config name.\nEach ConfigValue holds the value plus a human-readable editor label.\nSet at build time, edited by the user to tune behavior, read in SPy as kognitos.config.<name>."},"source_map":{"$ref":"#/components/schemas/v1SourceMap"},"code_length":{"type":"integer","format":"int32","description":"The length in characters of the SPy (Subset-of-Python) code.","readOnly":true},"kind":{"$ref":"#/components/schemas/v1AutomationKind"},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation, e.g. \"finance\", \"AP\".\nLabels belong to the automation, not to a version: changing them does not\ncreate a new version. Ordered case-insensitively.\nManaged via SetAutomationLabels.","readOnly":true}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"},"none_type":{"$ref":"#/components/schemas/v1ValueNoneType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE","VALUE_SCALAR_TYPE_TIMEDELTA"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type\n - VALUE_SCALAR_TYPE_TIMEDELTA: A timedelta value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1ValueNoneType":{"type":"object","title":"Represents a none value type that can hold no value"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1Position":{"type":"object","properties":{"line":{"type":"integer","format":"int32","description":"0-based line number."},"column":{"type":"integer","format":"int32","description":"0-based column offset (bytes from line start)."}},"description":"A position in a text document expressed as 0-based line and column."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"v1CodeManifest":{"type":"object","properties":{"code_hash":{"type":"string","description":"MD5 hash of the source code this manifest was generated from.\nUsed for staleness detection against ExecutionJournal.code_hash."},"main":{"$ref":"#/components/schemas/v1MainInfo"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeInput"},"description":"Inputs derived from main() parameter annotations."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeOutput"},"description":"Outputs derived from set_output() calls via type inference."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1Step"},"description":"Sequential steps corresponding to user-defined function calls in main()."},"title":{"type":"string","description":"Automation title — the first line of the module docstring."},"overview":{"type":"string","description":"Automation overview — the remainder of the module docstring (body)."}},"description":"CodeManifest describes the static interface, structure, and audit surface\nof analyzed SPy code."},"v1MainInfo":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"MainInfo contains location metadata for the main() function."},"commonv1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"},"start_position":{"$ref":"#/components/schemas/v1Position"},"end_position":{"$ref":"#/components/schemas/v1Position"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CodeInput":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the main() function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Args: section (join by name)."}},"description":"CodeInput represents a single input parameter derived from the main()\nfunction signature."},"v1CodeOutput":{"type":"object","properties":{"name":{"type":"string","description":"Output name (the key passed to set_output)."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the main() docstring Outputs: section (join by name)."}},"description":"CodeOutput represents a single output derived from set_output() calls."},"v1Step":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based sequential step number."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"entry_function":{"$ref":"#/components/schemas/v1FunctionNode"},"audit":{"$ref":"#/components/schemas/v1Audit"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Deprecated: moved to Audit.stops. Retained for compatibility; do not reuse\nfield number 5."},"title":{"type":"string","description":"Step title — the first line of the step function's docstring."},"overview":{"type":"string","description":"Step overview — the remainder of the step docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns)."},"rules":{"type":"array","items":{"type":"string"},"description":"Business rules called out for this step (docstring Rules: section)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1Param"},"description":"Step parameters, from the step function's docstring Args: section joined to\nthe signature (name + type + description)."},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section)."},"phase":{"type":"string","description":"Phase this step belongs to — the title from the nearest preceding\nphase(\"...\") marker in main(). Empty when the step precedes any marker.\nThe ordered phase list is derived by consumers from steps in order."}},"description":"Step represents a single top-level step in the analyzed code, corresponding\nto a user-defined function call in main()."},"v1FunctionNode":{"type":"object","properties":{"name":{"type":"string","description":"Function name."},"docstring":{"type":"string","description":"Verbatim docstring from the function definition.\nEmpty string when the function has no docstring (triggers a warning)."},"location":{"$ref":"#/components/schemas/commonv1Location"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/v1FunctionNode"},"description":"User-defined functions called within this function, in call order.\nRecursive calls stop at cycle boundaries (no loops in the tree)."}},"description":"FunctionNode represents a user-defined function in the recursive call tree.\nThe tree preserves call order within each function body, enabling UI sub-step\nprogress tracking and exception breadcrumbs.\nShared functions called from multiple steps appear in each step's tree at\ntheir respective call sites (each appearance = a distinct runtime invocation)."},"v1Audit":{"type":"object","properties":{"external_calls":{"type":"array","items":{"$ref":"#/components/schemas/v1ExternalCall"},"description":"Every kognitos.<conn>.<book>.<func>(...) call reachable transitively\nfrom this step's function."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/v1Literal"},"description":"Every string and numeric literal in the transitive call subtree.\nIncludes trivial values (0, \"\", None, etc.) — no filtering applied."},"collections":{"type":"array","items":{"$ref":"#/components/schemas/v1CollectionAccess"},"description":"Every first-class collection access reachable transitively from this\nstep's function. Reports the raw method invoked; consumers (e.g. Grimoire)\nclassify each access as a read or a write."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1AssetAccess"},"description":"Every read-only asset (file) reference reachable transitively from this\nstep's function, via the file(\"bishop://…\") constructor. Reports the raw\nURI as written; consumers resolve it."},"config_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1ConfigAccess"},"description":"Every kognitos.config.<name> read reachable transitively from this step's\nfunction (comparisons, computation, .format() templates, call kwargs).\nConfig is read-only, so every access is a read."},"stops":{"type":"array","items":{"$ref":"#/components/schemas/v1Stop"},"description":"Programmatic stop() sites reachable transitively from this step (an\noutcome-type site). A non-empty list means the step may terminate the run\nearly as a successful completion (not a \"stopped\" run). Presence is\nreachability-based, not \"always fires\" — stop() is typically guarded by a\nconditional, which static analysis does not evaluate."},"input_accesses":{"type":"array","items":{"$ref":"#/components/schemas/v1InputAccess"},"description":"Every main() input supplied directly as a positional or keyword argument\nto this step's call in main(). Each entry identifies the input and its\nargument location."}},"description":"Audit is a flat checklist of the reachable sites — dependencies and outcomes\n— for a step, collected transitively from the step's function through all\nnested user-defined calls."},"v1ExternalCall":{"type":"object","properties":{"call":{"type":"string","description":"Dotted path of the book function (e.g. \"kognitos.sap.purchase_order.read\")."},"containing_function":{"type":"string","description":"The user-defined function where this call appears."},"call_location":{"$ref":"#/components/schemas/commonv1Location"},"is_mutating":{"type":"boolean","description":"Whether the call changes the world (static-analysis-derived)."},"args":{"type":"array","items":{"$ref":"#/components/schemas/v1CallArg"},"description":"The call's keyword arguments, in source order."}},"description":"ExternalCall represents a book function call found in the transitive\ncall graph of a step."},"v1CallArg":{"type":"object","properties":{"name":{"type":"string","description":"Keyword name (e.g. \"recipients\", \"subject\")."},"location":{"$ref":"#/components/schemas/commonv1Location"},"type":{"$ref":"#/components/schemas/v1ValueType"},"literal":{"$ref":"#/components/schemas/commonv1Value"},"config":{"type":"string","description":"Config name (same format as ConfigAccess.name) — the argument reads\nkognitos.config.<name>. Join to the config schema to resolve its value."}},"description":"CallArg represents one keyword argument at an external call site. The source\noneof classifies the argument's value: an inline literal, a config reference,\nor — when neither arm is set — a computed value (a variable or expression not\nknown statically)."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Literal":{"type":"object","properties":{"value":{"type":"string","description":"The literal value as a string."},"containing_function":{"type":"string","description":"The user-defined function where this literal appears."}},"description":"Literal represents a string or numeric literal found in the transitive\ncall graph of a step."},"v1CollectionAccess":{"type":"object","properties":{"slug_name":{"type":"string","description":"Collection slug as written in the automation code (the human slug, not the\nresolved collection id)."},"method":{"type":"string","description":"The collection method invoked (e.g. \"get\", \"insert\", \"update\", \"delete\")."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"CollectionAccess represents a first-class collection operation found in the\ntransitive call graph of a step. The raw method name is reported as-is;\nconsumers classify it as a read or a write."},"v1AssetAccess":{"type":"object","properties":{"uri":{"type":"string","description":"Raw bishop:// URI exactly as written in the automation code."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"AssetAccess represents a read-only asset (file) reference found in the\ntransitive call graph of a step, via the file(\"bishop://…\") constructor."},"v1ConfigAccess":{"type":"object","properties":{"name":{"type":"string","description":"Config name, same format as the <name> in kognitos.config.<name>."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"ConfigAccess represents a kognitos.config.<name> read reachable transitively\nfrom a step. Read-only; the resolved value is joined from the config schema."},"v1Stop":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/commonv1Location"},"containing_function":{"type":"string","description":"The user-defined function where the stop() appears."}},"description":"Stop represents a programmatic stop() call reachable from a step's transitive\ncall graph — a point where the run may complete early. A stop() ends the run\nas a successful completion, not a \"stopped\" run."},"v1InputAccess":{"type":"object","properties":{"name":{"type":"string","description":"Input name, matching CodeInput.name in the code manifest."},"location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"InputAccess represents a main() input supplied directly to a step."},"v1Param":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name from the function signature."},"type":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","description":"Description from the docstring Args: entry (join by name)."}},"description":"Param represents a single named, typed, documented parameter of a step\nfunction (docstring Args: joined to the signature annotation)."},"v1CollectionRef":{"type":"object","properties":{"collection_id":{"type":"string","description":"The Bishop collection id that this slug resolves to."},"stage":{"$ref":"#/components/schemas/v1CollectionStage"}},"description":"CollectionRef references a first-class collection by the id it resolves to."},"v1CollectionStage":{"type":"string","enum":["COLLECTION_STAGE_UNSPECIFIED","COLLECTION_STAGE_DRAFT","COLLECTION_STAGE_PUBLISHED"],"default":"COLLECTION_STAGE_UNSPECIFIED","description":"CollectionStage identifies which stage of a collection a request targets.\n\n - COLLECTION_STAGE_UNSPECIFIED: Stage not specified.\n - COLLECTION_STAGE_DRAFT: The draft stage.\n - COLLECTION_STAGE_PUBLISHED: The published stage."},"v1ConfigValue":{"type":"object","properties":{"label":{"type":"string","description":"Human display name shown in the config editor."},"value":{"$ref":"#/components/schemas/commonv1Value"}},"description":"ConfigValue is a single business-tunable configuration value for an\nautomation: the value written when the automation is built, plus the\nhuman-readable label shown when tuning it. Config lets an end user adjust\nautomation behavior by editing values, without touching the code.\n\nConfig entries are carried in a map keyed by the config name (referenced in\ncode as kognitos.config.<name>); the name is not repeated on the message."},"v1SourceMap":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1SourceMapEntry"},"description":"List of entries mapping step labels to source locations."}},"description":"SourceMap contains the mapping between AOP step labels and their\nlocations in the original SPy source code."},"v1SourceMapEntry":{"type":"object","properties":{"step_label":{"type":"string","description":"Hierarchical step label (e.g. \"1\", \"1.2\", \"2.1.3\")."},"source_location":{"$ref":"#/components/schemas/commonv1Location"}},"description":"SourceMapEntry maps a single AOP step to its location in the original SPy source."},"v1AutomationKind":{"type":"string","enum":["AUTOMATION_KIND_UNSPECIFIED","AUTOMATION_KIND_QUILL","AUTOMATION_KIND_QUILL2"],"default":"AUTOMATION_KIND_UNSPECIFIED","description":"AutomationKind identifies which builder produced an automation. This also\ndetermines how the automation's logic is represented (see per-value docs).\n\n - AUTOMATION_KIND_UNSPECIFIED: Unspecified kind. For backward compatibility, consumers MUST treat this as\nAUTOMATION_KIND_QUILL for legacy automations that predate this field.\n - AUTOMATION_KIND_QUILL: Built by the original Quill. The automation mapping to spy are defined by\n`input_specs` and `code_mapping`.\n - AUTOMATION_KIND_QUILL2: Built by Quill2 (on Rain). The automation mapping to spy is defined in an\nopaque \"code_manifest.json\" artifact; `input_specs` and `code_mapping` are not\npopulated."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AutomationImportExportServiceImportAutomationBody":{"type":"object","properties":{"zip_resource":{"type":"string","description":"Bishop resource name of the ZIP bundle to import.\nFormat: organizations/{organization}/workspaces/{workspace}/files/{name}\nThe caller obtains this by uploading the exported bundle to Bishop in the\ntarget workspace; it is not a download URL."}},"description":"Request message for ImportAutomation.","required":["zip_resource"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:import":{"post":{"summary":"Import Automation","description":"Imports an exported automation ZIP bundle into a workspace as a new draft 0.1.\nConnections and triggers are re-wired via caller-supplied mappings.\nIf display_name conflicts with an existing automation in the target workspace,\nthe name is automatically resolved by prefixing with \"1 - \", \"2 - \", etc.\nFails with FAILED_PRECONDITION if the encryption key is not configured.\nFails with INVALID_ARGUMENT if the bundle is malformed or decryption fails.","operationId":"ImportAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ImportAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationImportExportServiceImportAutomationBody"}}},"required":true},"tags":["Automations"]}}}}
```

## List Automation Summaries

> ListAutomationSummaries returns a paginated list of lightweight automation\
> summaries. Unlike ListAutomations, it omits heavy fields (code, artifacts,\
> full english\_code text, etc.), making it well suited to list/grid views that\
> only need identifying and display metadata.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationSummariesResponse":{"type":"object","properties":{"automation_summaries":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationSummary"},"description":"The list of automation summaries for the current page.\nMay be empty if no automations match the request criteria."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"ListAutomationSummariesResponse returns a page of automation summaries and\npagination information."},"v1AutomationSummary":{"type":"object","properties":{"name":{"type":"string","title":"The automation name. Format:\norganizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name.","readOnly":true},"author_id":{"type":"string","description":"ID of the user who created this automation.","readOnly":true},"latest_published_version":{"type":"string","description":"Semantic version of the latest published version (format: major.minor).\nNull when there is no published version.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"version":{"type":"string","description":"Current (working) semantic version (format: major.minor).","readOnly":true},"description":{"type":"string","description":"Description of the automation's purpose.","readOnly":true},"has_english_code":{"type":"boolean","description":"True when the automation has English code. Exposed as a presence flag\n(not the full text) because the list UI only gates on its existence.","readOnly":true},"steps":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationStepSummary"},"description":"Ordered steps of the automation, in execution order.\n\nProjected from the automation's code manifest, which is where QUILL2\nautomations carry their logic — QUILL automations describe themselves\nthrough english_code instead. Empty whenever no manifest has been built\nfor the returned version.\n\nThis is a slim projection of common.v1.Step — see AutomationStepSummary.","readOnly":true},"labels":{"type":"array","items":{"type":"string"},"description":"User-defined labels on the automation. Ordered case-insensitively.","readOnly":true}},"description":"AutomationSummary is a lightweight projection of Automation for list views.\nIt intentionally omits heavy fields (code, english_code text, artifacts,\ncode_manifest, etc.) so listing many automations stays cheap.\n\nThis is a projection/view of the Automation resource, not a resource itself,\nso it deliberately carries no google.api.resource annotation."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"v1AutomationStepSummary":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"1-based position of the step in execution order.","readOnly":true},"title":{"type":"string","description":"Step title — the first line of the step's docstring.","readOnly":true},"overview":{"type":"string","description":"Step overview — the remainder of the step's docstring body, excluding the\nsections parsed into their own fields (Rules, Args, Returns).","readOnly":true},"returns":{"type":"string","description":"Prose description of what the step returns (docstring Returns: section).","readOnly":true},"phase":{"type":"string","description":"Phase this step belongs to, for grouping consecutive steps under a heading.\nEmpty when the step precedes any phase marker in the automation.","readOnly":true}},"description":"AutomationStepSummary is a lightweight projection of a single\ncommon.v1.CodeManifest step, carrying only the prose a list view renders.\n\nIt deliberately omits the heavy parts of common.v1.Step: the `audit`\nchecklist (every book call, literal, and collection/asset/config access\nreachable from the step) and `entry_function` (the recursive call tree).\nThose are collected transitively across the call graph, so carrying them for\nevery step of every automation on a page would defeat the purpose of a\nsummary. Read the full steps from Automation.code_manifest via GetAutomation.\n"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:listSummaries":{"get":{"summary":"List Automation Summaries","description":"ListAutomationSummaries returns a paginated list of lightweight automation\nsummaries. Unlike ListAutomations, it omits heavy fields (code, artifacts,\nfull english_code text, etc.), making it well suited to list/grid views that\nonly need identifying and display metadata.","operationId":"ListAutomationSummaries","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationSummariesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of summaries to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, at most 10 summaries will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nIf negative, an INVALID_ARGUMENT error will be returned.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomationSummaries` call.\nProvide this to retrieve the subsequent page of results.\nWhen paginating, all other parameters must match the call that provided the token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"show_deleted","description":"Filter to show/hide deleted automations. Deleted automations will be hidden by default.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, a CEL filtering expression.\n\nSupported fields for filtering:\n  - `state`: The automation state (e.g., DRAFT, PUBLISHED)\n  - `labels`: Automations carrying the label (case-insensitive match)\n\nExample filters:\n  - `labels:\"finance\"`\n  - `labels:\"finance\" OR labels:\"ap\"` (carries any of the labels)\n  - `labels:\"finance\" AND labels:\"ap\"` (carries all of the labels)","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Reserved for future use. Comma-separated list of fields to order results by.\nCurrently not implemented. Results are always ordered by `update_time desc`.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}}
```
