> 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/exceptions.md).

# Exceptions

Track exceptions, view analytics, manage agent events, and access troubleshooting guides.

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

> Get Exception

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Exception":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the exception.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"},"run":{"type":"string","title":"The run in which the exception occurred. The run must belong\nto the same workspace as the exception.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"location":{"$ref":"#/components/schemas/commonV1Location"},"message":{"type":"string","description":"The exception message generated by the interpreter."},"create_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was last updated.","readOnly":true},"state":{"$ref":"#/components/schemas/v1ExceptionState"},"automation":{"type":"string","title":"The automation that the exception belongs to. The automation of an exception\nis the automation that the run belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the exception. Generated by the exception service.\nRecently created exceptions may not yet have a description.","readOnly":true},"group":{"type":"string","description":"Groups are used to categorize exceptions\nCurrently support static groups: \"missing_values\", \"user_system_error\", \"internal_error\"\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nIn future, we may support dynamic groups.\nEmpty string means the exception is not grouped."},"resolution_guide_entry":{"type":"string","title":"The guide entry that was used to automatically resolve this exception.\nSet when the exception service successfully applies\na guide entry to resolve the exception i.e exception.state should be RESOLVED if this field is set.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}","readOnly":true},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"execution_id":{"type":"string","title":"The execution ID within the run where this exception occurred.\nUsed to differentiate exceptions at the same location with the same message.\nExample: \"exec_123abc\" or a UUID"},"extra":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra information about the exception."},"assignee":{"type":"string","title":"The user assigned to resolve this exception.\nFormat: users/{user}"},"resolver":{"type":"string","description":"The entity that resolved this exception.\nCan be either a user (for manual resolutions) or an agent (for automatic resolutions).\nFormat: users/{user} or agents/{agent}\nNote: No resource_reference is specified to avoid service dependencies and to support\nmultiple resource types in a single field."},"title":{"type":"string","description":"Short, business-friendly title for the exception.\nGenerated by the exception service (LLM) at create time alongside ``description``,\nand intended to be the primary one-line label that clients render in lists,\ntooltips, and notifications. May be empty for older exceptions that pre-date\ntitle generation.","readOnly":true},"step_index":{"type":"integer","format":"int32","description":"1-based index of the ``# @step`` block in the automation source that\ncontains the failing line for this exception. Zero (the proto default)\nmeans the exception did not fall inside a step block (the automation\nhad no step markers, or the failing line fell outside any covered\nrange). Clients should treat zero as \"no step\".\n\nDeprecated: no replacement. Still populated for existing clients; will\nstop being set in a future release. Do not build new behavior on it.","readOnly":true},"step_title":{"type":"string","description":"Human-readable label of the ``# @step`` block that contains the\nfailing line (paired with ``step_index``). Empty when\n``step_index`` is zero or when the step block has no title.\n\nDeprecated: no replacement. Still populated for existing clients; will\nstop being set in a future release. Do not build new behavior on it.","readOnly":true},"code":{"type":"string","description":"The SPY/AOP code content at the location where the exception occurred.\nProvided by the caller at creation time and not stored or returned."},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"The book connections that were active at the time this exception occurred.\nProvided by the caller at creation time and not stored or returned.\nMaps connection names to their specific ID and endpoints, mirroring the\nbook_connections field on the run's executable steps."},"rain_thread_id":{"type":"string","description":"The Rain thread ID for this exception on the Astral-on-Rain path.\nEach exception gets its own Rain thread so clients can subscribe to just\nthis exception's events. Empty on the local path or when Rain is disabled.","readOnly":true},"is_source_fix_required":{"type":"boolean","description":"Whether resolving this exception requires a fix to the automation source.\n\nDeprecated: no replacement. Still populated for existing clients; will\nstop being set in a future release. Do not build new behavior on it.\nNote this deprecates only the field on Exception -- the same-named\nrequest fields on MarkExceptionResolvedRequest and PatchStepRequest are\nunaffected.","readOnly":true},"runtime_values":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The runtime values of the variables of the function which contains failing sentence read,\nand the values they held (variable name -> value). Sourced from Jarvis\n``ExecutionFailed.error.context.runtime_values`` and forwarded by Jeeves.\nProvided by the caller at creation time and not stored or returned,\nmirroring ``connections``.\nEmpty is a legitimate state: parse errors, timeouts and panics carry no\nruntime values, and neither does a pre-v3.6.0 Jarvis."},"cluster":{"type":"string","description":"Generic symptom label for this exception, with every specific value\n(names, numbers, dates, file names) stripped out, so that two runs which\nfailed the same way share one ``cluster``. Generated by the exception\nservice (LLM) at create time in the same call as ``title`` and\n``description``. Clients use it to group same-symptom exceptions.\nMay be empty for older exceptions that pre-date cluster generation.","readOnly":true},"runtime_identifier":{"type":"string","description":"The single runtime value responsible for this exception -- one scalar such\nas a name, number, code or date -- which differentiates this exception\nfrom the others in its ``cluster``. Generated by the exception service\n(LLM) alongside ``cluster``. Empty is a legitimate state: it means no\nsingle value is responsible (and it is also empty for older exceptions\nthat pre-date runtime identifier generation).","readOnly":true},"typed_extra":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Extra information about the exception, as typed values that may be offloaded."}},"description":"An exception that occurred during an automation run.\nExceptions are raised by the interpreter and are analogous to Python exceptions.\nHowever, the Kognitos platform provides various mechanisms to resolve an\nexception and then resume the run.\nAutomation runs are important business processes for our users, so the expectation\nis that every exception needs to be resolved even if the resolution involves manual steps\nor abandoning the automation run.","required":["run","location","message"]},"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."},"v1ExceptionState":{"type":"string","enum":["EXCEPTION_STATE_UNSPECIFIED","EXCEPTION_STATE_PENDING","EXCEPTION_STATE_RESOLVED","EXCEPTION_STATE_ARCHIVED"],"default":"EXCEPTION_STATE_UNSPECIFIED","description":"The state of an exception.\n\n - EXCEPTION_STATE_UNSPECIFIED: The state is not specified.\n - EXCEPTION_STATE_PENDING: The exception is pending resolution.\nThis is the initial state when an exception is created.\nTransitions:\nOn creation --> PENDING\nPENDING --> RESOLVED: Exception successfully resolved (run can continue)\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\n - EXCEPTION_STATE_RESOLVED: The exception has been resolved.\nRESOLVED is a terminal state. Resolved exceptions are retained for historical records\nTransitions:\nPENDING --> RESOLVED: Exception resolved (run can continue)\n - EXCEPTION_STATE_ARCHIVED: The exception has been archived.\nArchived exceptions are retained for historical records and audit purposes.\nTransitions:\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\nARCHIVED --> PENDING: Exception unarchived (run can continue)"},"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."},"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."},"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}/exceptions/{exception_id}":{"get":{"summary":"Get Exception","operationId":"GetException","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Exception"}}}},"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":"exception_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

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

> List Exceptions

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListExceptionsResponse":{"type":"object","properties":{"exceptions":{"type":"array","items":{"$ref":"#/components/schemas/v1Exception"},"description":"The exceptions."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListExceptions`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of exceptions that match the given filter across all pages.\nThis count is not affected by page_size or page_token parameters."}},"description":"A response to a list exceptions request."},"v1Exception":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the exception.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"},"run":{"type":"string","title":"The run in which the exception occurred. The run must belong\nto the same workspace as the exception.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"location":{"$ref":"#/components/schemas/commonV1Location"},"message":{"type":"string","description":"The exception message generated by the interpreter."},"create_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was last updated.","readOnly":true},"state":{"$ref":"#/components/schemas/v1ExceptionState"},"automation":{"type":"string","title":"The automation that the exception belongs to. The automation of an exception\nis the automation that the run belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the exception. Generated by the exception service.\nRecently created exceptions may not yet have a description.","readOnly":true},"group":{"type":"string","description":"Groups are used to categorize exceptions\nCurrently support static groups: \"missing_values\", \"user_system_error\", \"internal_error\"\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nIn future, we may support dynamic groups.\nEmpty string means the exception is not grouped."},"resolution_guide_entry":{"type":"string","title":"The guide entry that was used to automatically resolve this exception.\nSet when the exception service successfully applies\na guide entry to resolve the exception i.e exception.state should be RESOLVED if this field is set.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}","readOnly":true},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"execution_id":{"type":"string","title":"The execution ID within the run where this exception occurred.\nUsed to differentiate exceptions at the same location with the same message.\nExample: \"exec_123abc\" or a UUID"},"extra":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra information about the exception."},"assignee":{"type":"string","title":"The user assigned to resolve this exception.\nFormat: users/{user}"},"resolver":{"type":"string","description":"The entity that resolved this exception.\nCan be either a user (for manual resolutions) or an agent (for automatic resolutions).\nFormat: users/{user} or agents/{agent}\nNote: No resource_reference is specified to avoid service dependencies and to support\nmultiple resource types in a single field."},"title":{"type":"string","description":"Short, business-friendly title for the exception.\nGenerated by the exception service (LLM) at create time alongside ``description``,\nand intended to be the primary one-line label that clients render in lists,\ntooltips, and notifications. May be empty for older exceptions that pre-date\ntitle generation.","readOnly":true},"step_index":{"type":"integer","format":"int32","description":"1-based index of the ``# @step`` block in the automation source that\ncontains the failing line for this exception. Zero (the proto default)\nmeans the exception did not fall inside a step block (the automation\nhad no step markers, or the failing line fell outside any covered\nrange). Clients should treat zero as \"no step\".\n\nDeprecated: no replacement. Still populated for existing clients; will\nstop being set in a future release. Do not build new behavior on it.","readOnly":true},"step_title":{"type":"string","description":"Human-readable label of the ``# @step`` block that contains the\nfailing line (paired with ``step_index``). Empty when\n``step_index`` is zero or when the step block has no title.\n\nDeprecated: no replacement. Still populated for existing clients; will\nstop being set in a future release. Do not build new behavior on it.","readOnly":true},"code":{"type":"string","description":"The SPY/AOP code content at the location where the exception occurred.\nProvided by the caller at creation time and not stored or returned."},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"The book connections that were active at the time this exception occurred.\nProvided by the caller at creation time and not stored or returned.\nMaps connection names to their specific ID and endpoints, mirroring the\nbook_connections field on the run's executable steps."},"rain_thread_id":{"type":"string","description":"The Rain thread ID for this exception on the Astral-on-Rain path.\nEach exception gets its own Rain thread so clients can subscribe to just\nthis exception's events. Empty on the local path or when Rain is disabled.","readOnly":true},"is_source_fix_required":{"type":"boolean","description":"Whether resolving this exception requires a fix to the automation source.\n\nDeprecated: no replacement. Still populated for existing clients; will\nstop being set in a future release. Do not build new behavior on it.\nNote this deprecates only the field on Exception -- the same-named\nrequest fields on MarkExceptionResolvedRequest and PatchStepRequest are\nunaffected.","readOnly":true},"runtime_values":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The runtime values of the variables of the function which contains failing sentence read,\nand the values they held (variable name -> value). Sourced from Jarvis\n``ExecutionFailed.error.context.runtime_values`` and forwarded by Jeeves.\nProvided by the caller at creation time and not stored or returned,\nmirroring ``connections``.\nEmpty is a legitimate state: parse errors, timeouts and panics carry no\nruntime values, and neither does a pre-v3.6.0 Jarvis."},"cluster":{"type":"string","description":"Generic symptom label for this exception, with every specific value\n(names, numbers, dates, file names) stripped out, so that two runs which\nfailed the same way share one ``cluster``. Generated by the exception\nservice (LLM) at create time in the same call as ``title`` and\n``description``. Clients use it to group same-symptom exceptions.\nMay be empty for older exceptions that pre-date cluster generation.","readOnly":true},"runtime_identifier":{"type":"string","description":"The single runtime value responsible for this exception -- one scalar such\nas a name, number, code or date -- which differentiates this exception\nfrom the others in its ``cluster``. Generated by the exception service\n(LLM) alongside ``cluster``. Empty is a legitimate state: it means no\nsingle value is responsible (and it is also empty for older exceptions\nthat pre-date runtime identifier generation).","readOnly":true},"typed_extra":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Extra information about the exception, as typed values that may be offloaded."}},"description":"An exception that occurred during an automation run.\nExceptions are raised by the interpreter and are analogous to Python exceptions.\nHowever, the Kognitos platform provides various mechanisms to resolve an\nexception and then resume the run.\nAutomation runs are important business processes for our users, so the expectation\nis that every exception needs to be resolved even if the resolution involves manual steps\nor abandoning the automation run.","required":["run","location","message"]},"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."},"v1ExceptionState":{"type":"string","enum":["EXCEPTION_STATE_UNSPECIFIED","EXCEPTION_STATE_PENDING","EXCEPTION_STATE_RESOLVED","EXCEPTION_STATE_ARCHIVED"],"default":"EXCEPTION_STATE_UNSPECIFIED","description":"The state of an exception.\n\n - EXCEPTION_STATE_UNSPECIFIED: The state is not specified.\n - EXCEPTION_STATE_PENDING: The exception is pending resolution.\nThis is the initial state when an exception is created.\nTransitions:\nOn creation --> PENDING\nPENDING --> RESOLVED: Exception successfully resolved (run can continue)\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\n - EXCEPTION_STATE_RESOLVED: The exception has been resolved.\nRESOLVED is a terminal state. Resolved exceptions are retained for historical records\nTransitions:\nPENDING --> RESOLVED: Exception resolved (run can continue)\n - EXCEPTION_STATE_ARCHIVED: The exception has been archived.\nArchived exceptions are retained for historical records and audit purposes.\nTransitions:\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\nARCHIVED --> PENDING: Exception unarchived (run can continue)"},"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."},"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."},"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}/exceptions":{"get":{"summary":"List Exceptions","operationId":"ListExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListExceptionsResponse"}}}},"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 exceptions to return. The service may return fewer than this value.\nIf unspecified, at most 50 exceptions will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListExceptions` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListExceptions` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"skip","description":"The number of exceptions to skip before returning results.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"filter","description":"The filter to apply to the list of exceptions.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- state: Exception state (PENDING, RESOLVED, ARCHIVED)\n- automation: Automation ID (exact match only)\n- create_time: Exception creation timestamp (ISO 8601 format)\n- group: Exception group (exact match only)\n  - Use group = \"value\" to match a specific group\n  - Use group = \"\" to match exceptions with no group assigned (ungrouped)\n- run: Run ID (exact match only)\n  - Use run = \"run1_id\" to match a specific run\n  - Use run = \"run1_id OR run2_id\" to match multiple runs\n\nSupported Operators:\n- Comparison: =, !=, <, <=, >, >=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n\nState Values:\n- PENDING or EXCEPTION_STATE_PENDING\n- RESOLVED or EXCEPTION_STATE_RESOLVED\n- ARCHIVED or EXCEPTION_STATE_ARCHIVED\n\nTimestamp Format:\n- ISO 8601 with Z suffix: \"2025-01-01T00:00:00Z\"\n- ISO 8601 with offset: \"2025-01-01T00:00:00+00:00\"\n\nExample Filters:\n- \"state = PENDING\" - List only pending exceptions\n- \"state != RESOLVED\" - List all non-resolved exceptions\n- \"automation = my-automation-id\" - List exceptions for a specific automation\n- \"state = PENDING AND automation = my-automation-id\" - Pending exceptions for an automation\n- \"state = PENDING OR state = ARCHIVED\" - Pending or archived exceptions\n- \"NOT state = RESOLVED\" - All non-resolved exceptions\n- \"create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Exceptions created after Jan 1, 2025\n- \"create_time >= \\\"2025-01-01T00:00:00Z\\\" AND create_time < \\\"2025-02-01T00:00:00Z\\\"\" - January 2025 exceptions\n- \"(state = PENDING OR state = ARCHIVED) AND create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Recent unresolved exceptions\n- \"group = \\\"missing_values\\\"\" - List exceptions in exactly the missing_values group\n- \"group = \\\"missing_values\\\" OR group = \\\"user_system_error\\\"\" - List exceptions in multiple groups\n- \"group = \\\"\\\"\" - List ungrouped exceptions (no group assigned)\n- \"state = PENDING AND group = \\\"\\\"\" - List pending ungrouped exceptions\n- \"group != \\\"\\\"\" - List all exceptions that have a group assigned (any group)\n- \"run = run1_id OR run = run2_id\" - List exceptions for multiple runs\n- \"run = run1_id\" - List exceptions for a specific run","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events

> List Events

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/v1Event"},"description":"The events in the conversation thread, ordered by creation time (newest first)."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListEvents`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of events in the conversation thread across all pages.\nThis count is not affected by page_size or page_token parameters."}},"description":"A response to a list events request."},"v1Event":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the event.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}"},"state":{"$ref":"#/components/schemas/v1EventState"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the event was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the event was last updated.","readOnly":true},"user_message":{"$ref":"#/components/schemas/v1UserMessage"},"agent_message":{"$ref":"#/components/schemas/v1AgentMessage"},"tool_call_request":{"$ref":"#/components/schemas/v1ToolCallRequest"},"tool_call_result":{"$ref":"#/components/schemas/v1ToolCallResult"},"thinking":{"$ref":"#/components/schemas/v1Thinking"},"system_message":{"$ref":"#/components/schemas/v1SystemMessage"},"completion_response":{"$ref":"#/components/schemas/v1CompletionResponse"},"exception":{"type":"string","title":"An optional exception resource name that the event belongs to.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"An event in a run conversation thread about an exception.\nEvents form a timeline of interactions between users, AI agents, and the system."},"v1EventState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_STREAMING","STATE_COMPLETE"],"default":"STATE_UNSPECIFIED","description":"The state of an event.\n\n - STATE_UNSPECIFIED: The state is not specified. This value is not used.\n - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.\n - STATE_COMPLETE: The event fields are done being generated."},"v1UserMessage":{"type":"object","properties":{"user":{"type":"string","title":"The user who authored the message.\nFormat: users/{user}"},"content":{"type":"string","description":"Simple text content."},"content_list":{"$ref":"#/components/schemas/v1InputContentList"}},"description":"A message from a user."},"v1InputContentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1InputContent"},"description":"The list of input content items."}},"description":"A list of input content items (can contain text and/or binary content).","required":["items"]},"v1InputContent":{"type":"object","properties":{"text":{"type":"string","description":"Text content."},"file":{"$ref":"#/components/schemas/v1FileInputContent"}},"description":"InputContent represents a single input item that can be text or binary."},"v1FileInputContent":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1FileContent"}},"description":"FileInputContent represents a file that can be either stored inline or referenced remotely."},"v1FileContent":{"type":"object","properties":{"mime_type":{"type":"string","description":"The MIME type of the file."},"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"filename":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"FileContent represents a file with its name and binary content.","required":["mime_type","content"]},"v1AgentMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A message from the AI agent."},"v1ToolCallRequest":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"display_name":{"type":"string","description":"The display name of the tool being called.","readOnly":true},"input":{"type":"string","description":"The input arguments passed to the tool. Contains arbitrary data in a tool-specific format\nthat the agent generates for the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call arguments.","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the tool call. Generated by the tool call service.","readOnly":true}},"description":"A tool call request made by the AI agent."},"v1ToolCallResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"result":{"type":"string","description":"The result of the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call result.","readOnly":true}},"description":"A tool call result returned by the tool."},"v1Thinking":{"type":"object","properties":{"content":{"type":"string","description":"The thinking content. CommonMark(GFM) formatted.","readOnly":true}},"description":"Thinking or reasoning by the AI agent."},"v1SystemMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the system message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A system-generated message."},"v1CompletionResponse":{"type":"object","properties":{"content":{"type":"string","description":"Final content if successful."},"error":{"type":"string","description":"Error description if the request failed."}},"description":"Terminal completion for the agent workflow."},"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}/runs/{run_id}/agents/{agent_id}/events":{"get":{"summary":"List Events","operationId":"ListEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListEventsResponse"}}}},"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":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of events to return. The service may return fewer than this value.\nIf unspecified, at most 50 events will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListEvents` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListEvents` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"The filter to apply to the list of events.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- exception: Exception Id\n\nSupported Operators:\n- Comparison: =, !=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n\nExample Filters:\n- \"exception = \\\"exc-123\\\"\" - Events for a specific exception\n- \"exception = \\\"exc-123\\\" OR exception = \\\"exc-456\\\"\" - Events for multiple exceptions","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events

> Create Event

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Event":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the event.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}"},"state":{"$ref":"#/components/schemas/v1EventState"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the event was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the event was last updated.","readOnly":true},"user_message":{"$ref":"#/components/schemas/v1UserMessage"},"agent_message":{"$ref":"#/components/schemas/v1AgentMessage"},"tool_call_request":{"$ref":"#/components/schemas/v1ToolCallRequest"},"tool_call_result":{"$ref":"#/components/schemas/v1ToolCallResult"},"thinking":{"$ref":"#/components/schemas/v1Thinking"},"system_message":{"$ref":"#/components/schemas/v1SystemMessage"},"completion_response":{"$ref":"#/components/schemas/v1CompletionResponse"},"exception":{"type":"string","title":"An optional exception resource name that the event belongs to.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"An event in a run conversation thread about an exception.\nEvents form a timeline of interactions between users, AI agents, and the system."},"v1EventState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_STREAMING","STATE_COMPLETE"],"default":"STATE_UNSPECIFIED","description":"The state of an event.\n\n - STATE_UNSPECIFIED: The state is not specified. This value is not used.\n - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.\n - STATE_COMPLETE: The event fields are done being generated."},"v1UserMessage":{"type":"object","properties":{"user":{"type":"string","title":"The user who authored the message.\nFormat: users/{user}"},"content":{"type":"string","description":"Simple text content."},"content_list":{"$ref":"#/components/schemas/v1InputContentList"}},"description":"A message from a user."},"v1InputContentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1InputContent"},"description":"The list of input content items."}},"description":"A list of input content items (can contain text and/or binary content).","required":["items"]},"v1InputContent":{"type":"object","properties":{"text":{"type":"string","description":"Text content."},"file":{"$ref":"#/components/schemas/v1FileInputContent"}},"description":"InputContent represents a single input item that can be text or binary."},"v1FileInputContent":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1FileContent"}},"description":"FileInputContent represents a file that can be either stored inline or referenced remotely."},"v1FileContent":{"type":"object","properties":{"mime_type":{"type":"string","description":"The MIME type of the file."},"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"filename":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"FileContent represents a file with its name and binary content.","required":["mime_type","content"]},"v1AgentMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A message from the AI agent."},"v1ToolCallRequest":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"display_name":{"type":"string","description":"The display name of the tool being called.","readOnly":true},"input":{"type":"string","description":"The input arguments passed to the tool. Contains arbitrary data in a tool-specific format\nthat the agent generates for the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call arguments.","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the tool call. Generated by the tool call service.","readOnly":true}},"description":"A tool call request made by the AI agent."},"v1ToolCallResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"result":{"type":"string","description":"The result of the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call result.","readOnly":true}},"description":"A tool call result returned by the tool."},"v1Thinking":{"type":"object","properties":{"content":{"type":"string","description":"The thinking content. CommonMark(GFM) formatted.","readOnly":true}},"description":"Thinking or reasoning by the AI agent."},"v1SystemMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the system message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A system-generated message."},"v1CompletionResponse":{"type":"object","properties":{"content":{"type":"string","description":"Final content if successful."},"error":{"type":"string","description":"Error description if the request failed."}},"description":"Terminal completion for the agent workflow."},"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}/runs/{run_id}/agents/{agent_id}/events":{"post":{"summary":"Create Event","operationId":"CreateEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Event"}}}},"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":"run_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/v1Event"}}},"description":"The event to create.\nIMPORTANT: Only user_message can be set when creating an event. The API will reject\nrequests that attempt to create events with agent_message, tool_call, thinking, or\nsystem_message set. These event types are automatically created by the system.","required":true},"tags":["Exceptions"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events/{event\_id}

> Get Event

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Event":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the event.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}"},"state":{"$ref":"#/components/schemas/v1EventState"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the event was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the event was last updated.","readOnly":true},"user_message":{"$ref":"#/components/schemas/v1UserMessage"},"agent_message":{"$ref":"#/components/schemas/v1AgentMessage"},"tool_call_request":{"$ref":"#/components/schemas/v1ToolCallRequest"},"tool_call_result":{"$ref":"#/components/schemas/v1ToolCallResult"},"thinking":{"$ref":"#/components/schemas/v1Thinking"},"system_message":{"$ref":"#/components/schemas/v1SystemMessage"},"completion_response":{"$ref":"#/components/schemas/v1CompletionResponse"},"exception":{"type":"string","title":"An optional exception resource name that the event belongs to.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"An event in a run conversation thread about an exception.\nEvents form a timeline of interactions between users, AI agents, and the system."},"v1EventState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_STREAMING","STATE_COMPLETE"],"default":"STATE_UNSPECIFIED","description":"The state of an event.\n\n - STATE_UNSPECIFIED: The state is not specified. This value is not used.\n - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.\n - STATE_COMPLETE: The event fields are done being generated."},"v1UserMessage":{"type":"object","properties":{"user":{"type":"string","title":"The user who authored the message.\nFormat: users/{user}"},"content":{"type":"string","description":"Simple text content."},"content_list":{"$ref":"#/components/schemas/v1InputContentList"}},"description":"A message from a user."},"v1InputContentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1InputContent"},"description":"The list of input content items."}},"description":"A list of input content items (can contain text and/or binary content).","required":["items"]},"v1InputContent":{"type":"object","properties":{"text":{"type":"string","description":"Text content."},"file":{"$ref":"#/components/schemas/v1FileInputContent"}},"description":"InputContent represents a single input item that can be text or binary."},"v1FileInputContent":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1FileContent"}},"description":"FileInputContent represents a file that can be either stored inline or referenced remotely."},"v1FileContent":{"type":"object","properties":{"mime_type":{"type":"string","description":"The MIME type of the file."},"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"filename":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"FileContent represents a file with its name and binary content.","required":["mime_type","content"]},"v1AgentMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A message from the AI agent."},"v1ToolCallRequest":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"display_name":{"type":"string","description":"The display name of the tool being called.","readOnly":true},"input":{"type":"string","description":"The input arguments passed to the tool. Contains arbitrary data in a tool-specific format\nthat the agent generates for the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call arguments.","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the tool call. Generated by the tool call service.","readOnly":true}},"description":"A tool call request made by the AI agent."},"v1ToolCallResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"result":{"type":"string","description":"The result of the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call result.","readOnly":true}},"description":"A tool call result returned by the tool."},"v1Thinking":{"type":"object","properties":{"content":{"type":"string","description":"The thinking content. CommonMark(GFM) formatted.","readOnly":true}},"description":"Thinking or reasoning by the AI agent."},"v1SystemMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the system message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A system-generated message."},"v1CompletionResponse":{"type":"object","properties":{"content":{"type":"string","description":"Final content if successful."},"error":{"type":"string","description":"Error description if the request failed."}},"description":"Terminal completion for the agent workflow."},"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}/runs/{run_id}/agents/{agent_id}/events/{event_id}":{"get":{"summary":"Get Event","operationId":"GetEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Event"}}}},"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":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events:stream

> Stream Events

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"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}/runs/{run_id}/agents/{agent_id}/events:stream":{"get":{"summary":"Stream Events","operationId":"StreamEvents","responses":{"200":{"description":"NDJSON stream of StreamEventsResponse objects (one JSON object per line)","content":{"application/x-ndjson":{"schema":{"type":"string","format":"binary","title":"NDJSON stream of StreamEventsResponse objects"}}}},"default":{"description":"An unexpected error response.","content":{"application/x-ndjson":{"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":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events:cancelGeneration

> Cancel Generation

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CancelGenerationResponse":{"type":"object","description":"Response for canceling ongoing event generation.\nEmpty response. Reserved for future extensibility."},"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}/runs/{run_id}/agents/{agent_id}/events:cancelGeneration":{"post":{"summary":"Cancel Generation","operationId":"CancelGeneration","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CancelGenerationResponse"}}}},"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":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

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

> List Exception Groups

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListExceptionGroupsResponse":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionGroup"},"description":"Available exception groups and their metadata."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."}},"description":"Response containing available exception groups."},"v1ExceptionGroup":{"type":"object","properties":{"name":{"type":"string","description":"The static types (e.g., \"missing_values\", \"user_system_error\", \"internal_error\").\ngroup name is fully qualified\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nThis is maintained by the system until we promote these to full resources.\nThis is the value used in the Exception.group field."},"title":{"type":"string","description":"Human-readable display name for UI."},"description":{"type":"string","description":"Description of what this group represents."},"suggested_action":{"type":"string","description":"Suggested action to resolve exceptions in this group."},"default_assignee":{"type":"string","title":"Default assignee for new exceptions in this group.\nWhen set, new exceptions in this group will be automatically assigned to this user.\nEmpty string means no default assignee is set.\nFormat: users/{user}"}},"description":"Groups are not full resources and cannot be created or modified via the API (for now)\nIn future, we may promote these to full resources."},"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}/exceptionGroups":{"get":{"summary":"List Exception Groups","operationId":"ListExceptionGroups","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListExceptionGroupsResponse"}}}},"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 groups to return.\nNote: Since groups are static and typically small in number,\npagination is not strictly necessary but included for AIP compliance.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token from a previous ListExceptionGroups call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptions:countByGroup

> Count Exceptions By Group

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountExceptionsByGroupResponse":{"type":"object","properties":{"group_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionGroupCount"},"description":"Exception counts by group, including metadata for each group."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"Total number of groups with exceptions (across all pages).\nRespects the filter from the request."},"total_exception_count":{"type":"integer","format":"int32","description":"Total count of all exceptions across all groups.\nRespects the filter from the request.\nThis is the sum of all counts in group_counts (across all pages).\nUseful for displaying summary statistics like \"110 total exceptions across 3 groups\"."}},"description":"Response containing exception counts by group."},"v1ExceptionGroupCount":{"type":"object","properties":{"group":{"$ref":"#/components/schemas/v1ExceptionGroup"},"count":{"type":"integer","format":"int32","description":"Number of exceptions in this group."}},"description":"Exception count for a specific group, including group metadata."},"v1ExceptionGroup":{"type":"object","properties":{"name":{"type":"string","description":"The static types (e.g., \"missing_values\", \"user_system_error\", \"internal_error\").\ngroup name is fully qualified\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nThis is maintained by the system until we promote these to full resources.\nThis is the value used in the Exception.group field."},"title":{"type":"string","description":"Human-readable display name for UI."},"description":{"type":"string","description":"Description of what this group represents."},"suggested_action":{"type":"string","description":"Suggested action to resolve exceptions in this group."},"default_assignee":{"type":"string","title":"Default assignee for new exceptions in this group.\nWhen set, new exceptions in this group will be automatically assigned to this user.\nEmpty string means no default assignee is set.\nFormat: users/{user}"}},"description":"Groups are not full resources and cannot be created or modified via the API (for now)\nIn future, we may promote these to full resources."},"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}/exceptions:countByGroup":{"get":{"summary":"Count Exceptions By Group","operationId":"CountExceptionsByGroup","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountExceptionsByGroupResponse"}}}},"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":"filter","description":"Optional filter to apply before counting (same syntax as ListExceptions).\nUse this to count within a specific state, automation, time range, etc.\nExample: \"state = PENDING\" to count only pending exceptions by group.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of groups to return.\nIf unspecified, at most 50 groups 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":"The page token from a previous CountExceptionsByGroup call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptions:countByAutomation

> Count Exceptions By Automation

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountExceptionsByAutomationResponse":{"type":"object","properties":{"automation_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionAutomationCount"},"description":"Exception counts by automation."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"Total number of automations with exceptions (across all pages).\nRespects the filter from the request."},"total_exception_count":{"type":"integer","format":"int32","description":"Total count of all exceptions across all automations.\nRespects the filter from the request.\nThis is the sum of all counts in automation_counts (across all pages).\nUseful for displaying summary statistics like \"500 total exceptions across 25 automations\"."}},"description":"Response containing exception counts by automation."},"v1ExceptionAutomationCount":{"type":"object","properties":{"automation":{"type":"string","title":"The automation resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}"},"count":{"type":"integer","format":"int32","description":"Number of exceptions for this automation."}},"description":"Exception count for a specific automation."},"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}/exceptions:countByAutomation":{"get":{"summary":"Count Exceptions By Automation","operationId":"CountExceptionsByAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountExceptionsByAutomationResponse"}}}},"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":"filter","description":"Optional filter to apply before counting (same syntax as ListExceptions).\nUse this to count within a specific state, group, time range, etc.\nExample: \"state = PENDING\" to count only pending exceptions by automation.\nExample: \"group = \\\"missing_values\\\"\" to count exceptions in missing_values group by automation.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of automations to return.\nIf unspecified, at most 50 automations 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":"The page token from a previous CountExceptionsByAutomation call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

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

> Get Guide Entry

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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}/guideEntries/{guide_entry_id}":{"get":{"summary":"Get Guide Entry","operationId":"GetGuideEntry","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}}},"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":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## Update Guide Entry

> Updates a TSG entry.\
> Only the content field can be updated.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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}/guideEntries/{guide_entry_id}":{"patch":{"summary":"Update Guide Entry","description":"Updates a TSG entry.\nOnly the content field can be updated.","operationId":"UpdateGuideEntry","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}}},"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":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"update_mask","description":"The list of fields to update.\nIf empty or unset, all mutable fields will be updated.\n\nMutable fields:\n- \"title\": Guide entry title\n- \"root_cause\": Root cause description\n- \"resolution_steps\": Resolution action and steps (Markdown)\n- \"resolution_code\": Example resolution code\n- \"resolution_notes\": Additional resolution notes (Markdown)\n- \"content\": (DEPRECATED) Use resolution_steps, resolution_code, and resolution_notes instead","in":"query","required":false,"schema":{"type":"string"}},{"name":"user","description":"The acting user, used by the server to attribute the new version row\nproduced by this update.\nFormat: users/{user}\n\nOptional: when omitted, the new version has no update attribution\n(the audit column is left NULL). Internal and test callers that do not\ncarry a user identity can omit it.","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"The guide entry to update.\nThe guide entry's `name` field is used to identify the entry to update."}}},"description":"The guide entry to update.\nThe guide entry's `name` field is used to identify the entry to update.","required":true},"tags":["Exceptions"]}}}}
```

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

> List Guide Entries

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListGuideEntriesResponse":{"type":"object","properties":{"guide_entries":{"type":"array","items":{"$ref":"#/components/schemas/v1GuideEntry"},"title":"The guide entries"},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListGuideEntries`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of guide entries across all pages.\nThis count respects the show_deleted parameter but is not affected by page_size or page_token."}},"title":"Response to a list guide entries request"},"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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}/guideEntries":{"get":{"summary":"List Guide Entries","operationId":"ListGuideEntries","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListGuideEntriesResponse"}}}},"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 guide entries to return. The service may return fewer than this value.\nIf unspecified, at most 50 guide entries will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListGuideEntries` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListGuideEntries` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"show_deleted","description":"If true, soft-deleted guide entries will be included in the results.\nDeleted entries have delete_time set.\nDefaults to false (deleted entries are filtered out).","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"filter","description":"The filter to apply to the list of guide entries.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- title: Guide entry title (partial match only)\n- resolution_steps: Resolution steps content (partial match only)\n- resolution_code: Resolution code content (partial match only)\n- resolution_notes: Resolution notes content (partial match only)\n- automation: Automation ID (exact match only)\n- create_time: Guide entry creation timestamp (ISO 8601 format)\n- update_time: Guide entry update timestamp (ISO 8601 format)\n- content: (DEPRECATED) Guide entry content - use resolution_steps, resolution_code, or resolution_notes instead\n\nSupported Operators:\n- Comparison: =, !=, <, <=, >, >=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n- Partial Match: contains\n\nExample Filters:\n- \"title contains 'My Guide Entry'\" - List guide entries with title containing \"My Guide Entry\"\n- \"resolution_steps contains 'restart'\" - List guide entries with resolution steps containing \"restart\"\n- \"resolution_code contains 'retry'\" - List guide entries with resolution code containing \"retry\"\n- \"automation = my-automation-id\" - List guide entries for a specific automation. Use \"-\" as the automation_id to list guide entries across all automations in the workspace.\n- \"automation = my-automation-id or automation = another-automation-id\" - List guide entries for specific automations.\n- \"create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Guide entries created after Jan 1, 2025\n- \"update_time >= \\\"2025-01-01T00:00:00Z\\\" AND update_time < \\\"2025-02-01T00:00:00Z\\\"\" - January 2025 guide entries\n- \"(title contains 'My Guide Entry' OR resolution_steps contains 'error') AND create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Recent guide entries with specific title or resolution steps","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## Create Guide Entry

> Creates a TSG entry for an automation. Created by the exception resolver\
> agent during resolution, or directly by users/clients over HTTP to author\
> a learning (kind="learning") that is not tied to a specific exception.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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}/guideEntries":{"post":{"summary":"Create Guide Entry","description":"Creates a TSG entry for an automation. Created by the exception resolver\nagent during resolution, or directly by users/clients over HTTP to author\na learning (kind=\"learning\") that is not tied to a specific exception.","operationId":"CreateGuideEntry","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}}},"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":"user","description":"The acting user, used by the server to attribute the creation of this\nguide entry.\nFormat: users/{user}\n\nOptional: when omitted, the created entry has no creation attribution\n(the audit column is left NULL). Internal and test callers that do not\ncarry a user identity can omit it.","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}},"description":"The guide entry to create","required":true},"tags":["Exceptions"]}}}}
```

## List Guide Applications

> Lists applications of a guide entry.\
> Returns a list of applications showing when and where the guide was applied.\
> UI can use this to fetch run details from Jeeves for the Applied Runs table.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListGuideApplicationsResponse":{"type":"object","properties":{"guide_applications":{"type":"array","items":{"$ref":"#/components/schemas/v1GuideApplication"},"title":"The guide applications"},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListGuideApplications`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of applications across all pages.\nThis count is not affected by page_size or page_token parameters."}},"title":"Response to a list guide applications request"},"v1GuideApplication":{"type":"object","properties":{"guide_entry":{"type":"string","title":"The guide entry resource name.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}","readOnly":true},"exception":{"type":"string","title":"The exception resource name.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}","readOnly":true},"run":{"type":"string","title":"The run resource name.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}","readOnly":true},"automation":{"type":"string","title":"The automation resource name.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}","readOnly":true},"applied_time":{"type":"string","format":"date-time","title":"When the guide was applied","readOnly":true}},"title":"A record of a guide entry being applied to resolve an exception"},"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}/guideEntries/{guide_entry_id}/applications":{"get":{"summary":"List Guide Applications","description":"Lists applications of a guide entry.\nReturns a list of applications showing when and where the guide was applied.\nUI can use this to fetch run details from Jeeves for the Applied Runs table.","operationId":"ListGuideApplications","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListGuideApplicationsResponse"}}}},"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":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of applications to return. The service may return fewer than this value.\nIf unspecified, at most 50 applications will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListGuideApplications` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListGuideApplications` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## List Guide Entry Versions

> Lists all versions of a guide entry, newest first (by DESC version order).\
> Unlike GetGuideEntry/ListGuideEntries (which return only the effective\
> version per entry), this returns the full version history for a single\
> guide entry so clients can inspect and revert to a previous version.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListGuideEntryVersionsResponse":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/v1GuideEntry"},"description":"The versions of the guide entry, ordered newest first.\nEach version shares the same guide entry `name` and is distinguished by\nits `version` field."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results. Empty when there are no more."},"total_size":{"type":"integer","format":"int32","description":"The total number of versions across all pages."}},"description":"Response to a list guide entry versions request."},"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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}/guideEntries/{guide_entry_id}:listVersions":{"get":{"summary":"List Guide Entry Versions","description":"Lists all versions of a guide entry, newest first (by DESC version order).\nUnlike GetGuideEntry/ListGuideEntries (which return only the effective\nversion per entry), this returns the full version history for a single\nguide entry so clients can inspect and revert to a previous version.","operationId":"ListGuideEntryVersions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListGuideEntryVersionsResponse"}}}},"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":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of versions to return. The service may return fewer.\nIf unspecified, at most 50 versions 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":"The page token, received from a previous `ListGuideEntryVersions` call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## Revert Guide Entry

> Reverts a guide entry to a previous version.\
> Forward-only (like grimoire's RestoreAutomation): copies the target\
> version's content into a NEW version row with a bumped minor version and\
> state = PENDING\_APPROVAL. No rows are removed and no pointer is moved\
> backward. Like an ordinary update, the new version becomes the latest\
> version but must be approved before the agent auto-applies it. The new\
> version records which version it was reverted from.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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":{}},"TroubleshootingGuideServiceRevertGuideEntryBody":{"type":"object","properties":{"version":{"type":"string","description":"The target version to revert to, in \"major.minor\" form (e.g. \"0.3\").\nMust be an existing version of this guide entry."},"user":{"type":"string","description":"Optional: when omitted, the new version has no attribution (the audit\ncolumn is left NULL). Internal and test callers can omit it.","title":"The acting user, used by the server to attribute the new version row\nproduced by the revert.\nFormat: users/{user}"}},"description":"Request to revert a guide entry to a previous version.","required":["version"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}:revert":{"post":{"summary":"Revert Guide Entry","description":"Reverts a guide entry to a previous version.\nForward-only (like grimoire's RestoreAutomation): copies the target\nversion's content into a NEW version row with a bumped minor version and\nstate = PENDING_APPROVAL. No rows are removed and no pointer is moved\nbackward. Like an ordinary update, the new version becomes the latest\nversion but must be approved before the agent auto-applies it. The new\nversion records which version it was reverted from.","operationId":"RevertGuideEntry","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}}},"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":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TroubleshootingGuideServiceRevertGuideEntryBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Transition Guide Entry State

> Transitions a guide entry to a new state.\
> \- PENDING\_APPROVAL -> APPROVED: Approve the guide entry for use by the agent\
> \- PENDING\_APPROVAL -> REJECTED: Reject the guide entry\
> \- Any state -> ARCHIVED: Archive the guide entry (soft deletes and updates the delete time)

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n  for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n  - resolution_steps: The primary resolution instructions\n  - resolution_code: Supporting code examples\n  - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."},"kind":{"type":"string","description":"Free-form category used to organize guide entries by origin or type.\nCaller-provided; the server defaults this to \"resolution\" when left empty.\n\"resolution\" entries are exception resolutions (the historical behavior and\nthe only kind agents produce while resolving an exception). Other values\n(e.g. \"learning\") denote general, possibly human-authored guidance that may\nnot be tied to any exception."},"approver":{"type":"string","description":"Acting user who approved the current version of this guide entry via\nTransitionGuideEntryState(ACTION_APPROVE).\nFormat: users/{user}\nEmpty when the entry has never been approved.","readOnly":true},"reverted_from":{"type":"string","description":"Semantic version (format: major.minor) this version was reverted from,\nwhen this version was produced by RevertGuideEntry. Empty when the version\nwas produced by a create or an ordinary update rather than a revert.\nExamples: \"0.3\", \"1.0\".","readOnly":true}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"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":{}},"TroubleshootingGuideServiceTransitionGuideEntryStateBody":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/TransitionGuideEntryStateRequestAction"},"user":{"type":"string","description":"Optional: when omitted, the transition has no attribution\n(the audit column is left NULL). Internal and test callers that do not\ncarry a user identity can omit it.","title":"The acting user, used by the server to attribute the transition of this\nguide entry.\nFormat: users/{user}"}},"title":"Request to transition a guide entry to a new state","required":["action"]},"TransitionGuideEntryStateRequestAction":{"type":"string","enum":["ACTION_UNSPECIFIED","ACTION_APPROVE","ACTION_REJECT","ACTION_ARCHIVE"],"default":"ACTION_UNSPECIFIED","description":"Actions that can be performed on a guide entry.\n\n - ACTION_UNSPECIFIED: Action is not specified.\n - ACTION_APPROVE: Approve the guide entry.\nTransitions from PENDING_APPROVAL to APPROVED.\nApproved guide entries can be used by the agent to resolve exceptions.\n - ACTION_REJECT: Reject the guide entry.\nTransitions from PENDING_APPROVAL to REJECTED.\nRejected guide entries will not be used by the agent.\n - ACTION_ARCHIVE: Archive the guide entry.\nCan be performed from any state.\nArchived guide entries are retained for historical purposes but not used by the agent."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}:transitionState":{"post":{"summary":"Transition Guide Entry State","description":"Transitions a guide entry to a new state.\n- PENDING_APPROVAL -> APPROVED: Approve the guide entry for use by the agent\n- PENDING_APPROVAL -> REJECTED: Reject the guide entry\n- Any state -> ARCHIVED: Archive the guide entry (soft deletes and updates the delete time)","operationId":"TransitionGuideEntryState","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}}},"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":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TroubleshootingGuideServiceTransitionGuideEntryStateBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Query Guide Stats

> Queries usage statistics for guide entries.\
> Returns aggregated statistics including total occurrences\
> and filtered occurrences within an optional date range.\
> This is a custom method for analytics/reporting, not a standard List operation.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1QueryGuideStatsResponse":{"type":"object","properties":{"stats":{"type":"array","items":{"$ref":"#/components/schemas/v1GuideStats"},"title":"Statistics for each guide entry"},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in a subsequent `QueryGuideStats` call to continue listing results.\nWill be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of guide entries with statistics across all pages.\nThis count is not affected by pagination parameters."}},"title":"Response to a query guide statistics request"},"v1GuideStats":{"type":"object","properties":{"guide_entry":{"type":"string","title":"The guide entry resource name.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}","readOnly":true},"total_occurrences":{"type":"integer","format":"int32","title":"Total number of times this guide has been applied to resolve exceptions","readOnly":true},"filtered_occurrences":{"type":"integer","format":"int32","description":"Number of times this guide has been applied within the requested date range.\nIf no date range was specified in the request, equals total_occurrences.","readOnly":true},"successful_occurrences":{"type":"integer","format":"int32","description":"Number of applications that durably resolved the exception, i.e. the same\nfailure (matching error message at a nearby code location) did not recur\nlater in the same run. Always <= total_occurrences.","readOnly":true},"success_rate":{"type":"number","format":"float","description":"The durable success rate of this guide: successful_occurrences /\ntotal_occurrences, in the range [0, 1]. Zero when total_occurrences is 0.\n\"Success\" means the same failure did not recur in the run after the guide\nwas applied; it is a durability proxy, not a guarantee the business outcome\nwas correct.","readOnly":true}},"title":"Usage statistics for a guide entry"},"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":{}},"TroubleshootingGuideServiceQueryGuideStatsBody":{"type":"object","properties":{"filter":{"type":"string","description":"The filter to apply when querying guide statistics.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- guide_entry: Guide entry ID (not full resource name)\n- start_time: Filter applications from this time (inclusive, ISO 8601 format)\n- end_time: Filter applications until this time (exclusive, ISO 8601 format)\n\nSupported Operators:\n- Comparison: =, !=, <, <=, >, >=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n\nTimestamp Format:\n- ISO 8601 with Z suffix: \"2025-01-01T00:00:00Z\"\n- ISO 8601 with offset: \"2025-01-01T00:00:00+00:00\"\n\nFiltering Behavior:\n- The date range filters (start_time, end_time) apply to the filtered_occurrences count\n- The total_occurrences count always reflects all-time data regardless of time filters\n\nExample Filters:\n- \"\" - Get statistics for all guide entries under parent\n- \"guide_entry = my-guide-id\" - Statistics for a specific guide entry\n- \"guide_entry = id1 OR guide_entry = id2\" - Statistics for specific guide entries\n- \"start_time >= \\\"2025-01-01T00:00:00Z\\\"\" - Applications from Jan 1, 2025 onwards\n- \"start_time >= \\\"2025-01-01T00:00:00Z\\\" AND end_time < \\\"2025-02-01T00:00:00Z\\\"\" - Applications in January 2025\n- \"guide_entry = my-guide-id AND start_time >= \\\"2025-01-01T00:00:00Z\\\"\" - Specific guide's applications from Jan 1, 2025"},"page_size":{"type":"integer","format":"int32","description":"The maximum number of guide entries with statistics to return.\nIf unspecified, at most 100 guide entries will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000."},"page_token":{"type":"string","description":"The page token, received from a previous `QueryGuideStats` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, the filter parameter must match the call that provided the page token."}},"title":"Request to query guide statistics"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries:queryStats":{"post":{"summary":"Query Guide Stats","description":"Queries usage statistics for guide entries.\nReturns aggregated statistics including total occurrences\nand filtered occurrences within an optional date range.\nThis is a custom method for analytics/reporting, not a standard List operation.","operationId":"QueryGuideStats","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1QueryGuideStatsResponse"}}}},"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/TroubleshootingGuideServiceQueryGuideStatsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Create Run Assistant

> Creates an interactive AI assistant (a Rain thread) for a run, pre-staged\
> with the automation's code and connections. Returns the rain\_thread\_id.\
> Despite the "Create" prefix this is a custom action, not an AIP-133 standard\
> Create: it has no resource body (the only input is the parent run, bound from\
> the path) and returns a thread id rather than a resource.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CreateRunAssistantResponse":{"type":"object","properties":{"rain_thread_id":{"type":"string","description":"The Rain thread id for this run assistant session.","readOnly":true}},"description":"Response containing the created run assistant's Rain thread id."},"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}/runs/{run_id}:runAssistant":{"post":{"summary":"Create Run Assistant","description":"Creates an interactive AI assistant (a Rain thread) for a run, pre-staged\nwith the automation's code and connections. Returns the rain_thread_id.\nDespite the \"Create\" prefix this is a custom action, not an AIP-133 standard\nCreate: it has no resource body (the only input is the parent run, bound from\nthe path) and returns a thread id rather than a resource.","operationId":"CreateRunAssistant","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CreateRunAssistantResponse"}}}},"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":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## List Exception Clusters

> Lists exception clusters -- one row per distinct symptom, aggregated\
> server-side so a client never has to hold every exception to group them.\
> A cluster is (automation, automation\_version, cluster label): a fix ships\
> as a new version, so the same symptom on two versions is two problems.\
> Clusters are derived from Exception.cluster rather than stored, so they are\
> not yet resources; ExceptionGroup sets the same precedent.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListExceptionClustersResponse":{"type":"object","properties":{"clusters":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionCluster"},"description":"The clusters on this page, in the requested order."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"Total number of distinct clusters (across all pages).\nRespects the filter from the request."},"total_exception_count":{"type":"integer","format":"int32","description":"Total count of exceptions across all clusters (across all pages).\nRespects the filter from the request. This is the sum of member_count over\nevery cluster, not just the ones on this page."}},"description":"Response containing a page of exception clusters."},"v1ExceptionCluster":{"type":"object","properties":{"name":{"type":"string","description":"{cluster} is an OPAQUE token. Pass it (the last path segment) to the\n`cluster_key` filter field on ListExceptions to list this cluster's\nmembers. Do NOT parse or construct it: it currently encodes the automation,\nthe version and the normalised label, and will encode a stored cluster id\nonce clusters become real resources.","title":"The cluster address.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionClusters/{cluster}"},"cluster":{"type":"string","description":"The generic symptom label shared by every member, taken from the\nrepresentative -- the headline a client shows on the row. Never an\nidentifier; two wordings of one symptom are two clusters.\nEmpty for single-exception clusters whose exception pre-dates cluster\ngeneration; clients fall back to the member's own title."},"automation":{"type":"string","description":"The automation these exceptions occurred on. Matches\nException.automation, which carries the raw automation id."},"automation_version":{"type":"string","description":"The automation version these exceptions ran on (e.g. \"1.0\").\nEmpty when the run carried no version. Part of the cluster identity: the\nsame symptom before and after a fix shipped is two problems, and merging\nthem would hide a regression behind a growing count."},"member_count":{"type":"integer","format":"int32","description":"Number of exceptions in this cluster, after the request filter."},"held_count":{"type":"integer","format":"int32","description":"How many of those members are still PENDING. Less than member_count when\nsome have settled -- which is what a bulk action moves, since only PENDING\nexceptions can be archived or retried."},"oldest_create_time":{"type":"string","format":"date-time","description":"Creation time of the oldest member. Paired with newest_create_time this is\nthe span the cluster covers, which answers \"is this still happening\"."},"newest_create_time":{"type":"string","format":"date-time","description":"Creation time of the newest member."},"last_activity_time":{"type":"string","format":"date-time","description":"Most recent update to any member. What CLUSTER_ORDER_RECENCY sorts on."},"representative":{"type":"string","description":"The member to work: the oldest still-held exception, or the oldest member\nwhen none are held. Working one that has already settled wastes the\noperator's turn.\n\nChosen server-side rather than by the client, because the client sees only\nthe members it has fetched: on a cluster larger than one page its own\n\"first member\" would be the wrong exception.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"A group of exceptions that failed the same way on the same automation\nversion -- one row per problem rather than one per stopped run.\n\nNot a resource: clusters are computed from Exception.cluster at read time and\nhave no stored identity, so `name` is a system-maintained address rather than\nan addressable resource. ExceptionGroup sets the same precedent."},"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}/exceptionClusters":{"get":{"summary":"List Exception Clusters","description":"Lists exception clusters -- one row per distinct symptom, aggregated\nserver-side so a client never has to hold every exception to group them.\nA cluster is (automation, automation_version, cluster label): a fix ships\nas a new version, so the same symptom on two versions is two problems.\nClusters are derived from Exception.cluster rather than stored, so they are\nnot yet resources; ExceptionGroup sets the same precedent.","operationId":"ListExceptionClusters","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListExceptionClustersResponse"}}}},"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":"filter","description":"Optional filter applied to exceptions BEFORE aggregation (same syntax as\nListExceptions). Every count and timestamp on the returned clusters\nrespects it.\nExample: a queue lane that keeps recently-settled runs visible sends\n'state = \"PENDING\" OR (state = \"RESOLVED\" AND update_time > \"...\")'.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of clusters to return.\nIf unspecified, at most 50 clusters 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":"The page token from a previous ListExceptionClusters call.","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"How to rank the clusters. Defaults to CLUSTER_ORDER_URGENCY.\n\n - CLUSTER_ORDER_UNSPECIFIED: Defaults to CLUSTER_ORDER_URGENCY.\n - CLUSTER_ORDER_URGENCY: Biggest class first: most members, oldest first among equals. For work\nstill held, where one conversation buys the most.\n - CLUSTER_ORDER_AGE: Longest-waiting run first, whatever size class it sits in. The counterpart\nto urgency, not a variation on it: a single run stuck since this morning\noutranks a class of six that started ten minutes ago.\n - CLUSTER_ORDER_RECENCY: Most recent activity first. For work already settled, where size means\nnothing and the only useful question is what happened last.","in":"query","required":false,"schema":{"type":"string","enum":["CLUSTER_ORDER_UNSPECIFIED","CLUSTER_ORDER_URGENCY","CLUSTER_ORDER_AGE","CLUSTER_ORDER_RECENCY"],"default":"CLUSTER_ORDER_UNSPECIFIED"}}],"tags":["Exceptions"]}}}}
```

## Set Exception Group Routing

> Sets default assignees for exception groups in a workspace.\
> Sets or clears the default assignee for one or more exception groups.\
> When a default assignee is set for a group, new exceptions in that group\
> will be automatically assigned to that user at creation time.\
> Set default\_assignee to "" to clear the default (no auto-assignment).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1SetExceptionGroupRoutingResponse":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionGroup"},"description":"The updated exception groups with their routing configuration."}},"description":"Response for setting exception group routing."},"v1ExceptionGroup":{"type":"object","properties":{"name":{"type":"string","description":"The static types (e.g., \"missing_values\", \"user_system_error\", \"internal_error\").\ngroup name is fully qualified\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nThis is maintained by the system until we promote these to full resources.\nThis is the value used in the Exception.group field."},"title":{"type":"string","description":"Human-readable display name for UI."},"description":{"type":"string","description":"Description of what this group represents."},"suggested_action":{"type":"string","description":"Suggested action to resolve exceptions in this group."},"default_assignee":{"type":"string","title":"Default assignee for new exceptions in this group.\nWhen set, new exceptions in this group will be automatically assigned to this user.\nEmpty string means no default assignee is set.\nFormat: users/{user}"}},"description":"Groups are not full resources and cannot be created or modified via the API (for now)\nIn future, we may promote these to full resources."},"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":{}},"ExceptionManagerServiceSetExceptionGroupRoutingBody":{"type":"object","properties":{"routing_rules":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionGroupRoutingRule"},"description":"The routing rules to set. Each rule maps a group to a default assignee.\nRules for groups not included in this list are left unchanged."}},"description":"Request to update default assignees for exception groups in a workspace.\nThis is an upsert operation: existing routing rules for the specified groups\nare updated, and new rules are created for groups that don't have one yet.","required":["routing_rules"]},"v1ExceptionGroupRoutingRule":{"type":"object","properties":{"group":{"type":"string","description":"The exception group identifier (e.g., \"missing_values\", \"user_system_error\").\nThis is the short group ID, not the fully qualified name."},"default_assignee":{"type":"string","description":"The default assignee for new exceptions in this group.\nFormat: users/{user}\nSet to \"\" to clear the default assignee (no auto-assignment for this group)."}},"description":"A routing rule that maps an exception group to a default assignee.","required":["group","default_assignee"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups:setRouting":{"post":{"summary":"Set Exception Group Routing","description":"Sets default assignees for exception groups in a workspace.\nSets or clears the default assignee for one or more exception groups.\nWhen a default assignee is set for a group, new exceptions in that group\nwill be automatically assigned to that user at creation time.\nSet default_assignee to \"\" to clear the default (no auto-assignment).","operationId":"SetExceptionGroupRouting","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1SetExceptionGroupRoutingResponse"}}}},"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/ExceptionManagerServiceSetExceptionGroupRoutingBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Get Hermes Exception Context

> Returns the opening \`\<exception>\` payload for the Hermes agent.\
> \
> Hermes has no tool for reading the exception it was raised on, so this\
> payload IS its knowledge of what failed: the interpreter message, the\
> failing location, the variables the failing statement read and the values\
> they held, the run's inputs, and a window of the source around the line\
> that raised. The caller opens the Rain thread itself and sends this as (or\
> ahead of) the operator's first message.\
> \
> Read-only and idempotent, so a caller that lost the payload -- a page\
> reload, a second browser tab -- asks again rather than reconstructing it.\
> That is the point: the payload lives here, not in whatever opened the\
> thread.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GetHermesExceptionContextResponse":{"type":"object","properties":{"content":{"type":"string","description":"The `<exception>` block, ready to send to the agent verbatim.\n\nA part with nothing recorded behind it is left out rather than sent empty:\nthe agent's instructions branch on whether a source window is present, and\nan empty tag claiming to be the source is worse than no tag. So a thin\npayload is a successful response, not an error.","readOnly":true}},"description":"The rendered `<exception>` payload."},"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}/exceptions/{exception_id}:hermesContext":{"get":{"summary":"Get Hermes Exception Context","description":"Returns the opening `<exception>` payload for the Hermes agent.\n\nHermes has no tool for reading the exception it was raised on, so this\npayload IS its knowledge of what failed: the interpreter message, the\nfailing location, the variables the failing statement read and the values\nthey held, the run's inputs, and a window of the source around the line\nthat raised. The caller opens the Rain thread itself and sends this as (or\nahead of) the operator's first message.\n\nRead-only and idempotent, so a caller that lost the payload -- a page\nreload, a second browser tab -- asks again rather than reconstructing it.\nThat is the point: the payload lives here, not in whatever opened the\nthread.","operationId":"GetHermesExceptionContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetHermesExceptionContextResponse"}}}},"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":"exception_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## Archive Exceptions

> Archives PENDING exceptions matching a filter.\
> Transitions exceptions from PENDING to ARCHIVED state.\
> RESOLVED exceptions are ignored (already complete, no need to archive).\
> Use this when giving up on unresolved exceptions.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ArchiveExceptionsResponse":{"type":"object","properties":{"archived_count":{"type":"integer","format":"int32","description":"Number of exceptions transitioned from PENDING to ARCHIVED state."}},"description":"Response for archiving exceptions."},"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":{}},"ExceptionManagerServiceArchiveExceptionsBody":{"type":"object","properties":{"filter":{"type":"string","title":"Filter to apply before archiving. Filter is required as a safeguard to prevent archiving ALL exceptions in workspace.\nOnly PENDING exceptions matching the filter will be archived. Non-PENDING exceptions are ignored by the implementation.\nAllowed fields: run, automation, create_time, group\nExample: \"automation = my-automation-id\" - Archives all pending exceptions for an automation\nExample: \"automation = my-automation-id AND create_time < \\\"2025-01-01T00:00:00Z\\\"\" - Archives old pending exceptions\nExample: \"run = run1_id OR run = run2_id\" - Archives pending exceptions for multiple runs"}},"description":"Request to archive exceptions.","required":["filter"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:archive":{"post":{"summary":"Archive Exceptions","description":"Archives PENDING exceptions matching a filter.\nTransitions exceptions from PENDING to ARCHIVED state.\nRESOLVED exceptions are ignored (already complete, no need to archive).\nUse this when giving up on unresolved exceptions.","operationId":"ArchiveExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ArchiveExceptionsResponse"}}}},"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/ExceptionManagerServiceArchiveExceptionsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Assign Exceptions

> Assigns exceptions to a user.\
> Supports three assignment scopes:\
> 1\. Single exception: set \`name\` to target one exception.\
> 2\. Group + automation: set \`filter\` with group and automation to target exceptions\
> &#x20;  for a specific group within a specific automation.\
> 3\. Group + workspace: set \`filter\` with group only to target all exceptions\
> &#x20;  for a group across the entire workspace.\
> Set \`assignee\` to "" to clear the assignment.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AssignExceptionsResponse":{"type":"object","properties":{"assigned_count":{"type":"integer","format":"int32","description":"Number of exceptions that were assigned (or unassigned)."}},"description":"Response for assigning exceptions."},"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":{}},"ExceptionManagerServiceAssignExceptionsBody":{"type":"object","properties":{"assignee":{"type":"string","description":"The user to assign to the exceptions.\nFormat: users/{user}\nSet to \"\" to clear the assignment (unassign)."},"name":{"type":"string","title":"Assign a single exception by its full resource name.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"},"filter":{"type":"string","description":"Example: \"group = \\\"missing_values\\\"\" - Assign all pending missing_values exceptions\nExample: \"group = \\\"missing_values\\\" AND automation = \\\"auto-123\\\"\" - Assign missing_values for a specific automation\nExample: \"automation = \\\"auto-123\\\"\" - Assign all pending exceptions for an automation","title":"Filter to select exceptions for bulk assignment.\nFollows Google AIP-160 filtering standard.\nSupported fields: group, automation, create_time, run, stage"}},"description":"Request to assign exceptions to a user.\nSupports three assignment scopes via the target field:\n1. Single exception: set `name` to assign one specific exception.\n2. Filtered exceptions: set `filter` to assign exceptions matching AIP-160 criteria.\n   Use this for group-level or automation-level assignment.\n\nAssignment behavior:\n- Only PENDING exceptions are assigned. RESOLVED/ARCHIVED exceptions are skipped.\n- Set `assignee` to \"\" to clear the assignment (unassign).\n- The response returns the number of exceptions that were updated.","required":["assignee"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:assign":{"post":{"summary":"Assign Exceptions","description":"Assigns exceptions to a user.\nSupports three assignment scopes:\n1. Single exception: set `name` to target one exception.\n2. Group + automation: set `filter` with group and automation to target exceptions\n   for a specific group within a specific automation.\n3. Group + workspace: set `filter` with group only to target all exceptions\n   for a group across the entire workspace.\nSet `assignee` to \"\" to clear the assignment.","operationId":"AssignExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AssignExceptionsResponse"}}}},"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/ExceptionManagerServiceAssignExceptionsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Count Exceptions By Assignee

> Counts exceptions by assignee.\
> Returns a list of assignees with their exception counts.\
> Useful for workload distribution dashboards and identifying unassigned exceptions.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountExceptionsByAssigneeResponse":{"type":"object","properties":{"assignee_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionAssigneeCount"},"description":"Exception counts by assignee."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"Total number of distinct assignees with exceptions (across all pages).\nRespects the filter from the request.\nIncludes unassigned (null assignee) as a separate entry if applicable."},"total_exception_count":{"type":"integer","format":"int32","description":"Total count of all exceptions across all assignees.\nRespects the filter from the request.\nThis is the sum of all counts in assignee_counts (across all pages)."}},"description":"Response containing exception counts by assignee."},"v1ExceptionAssigneeCount":{"type":"object","properties":{"assignee":{"type":"string","description":"The assignee resource name.\nFormat: users/{user}\nEmpty string represents unassigned exceptions.","readOnly":true},"count":{"type":"integer","format":"int32","description":"Number of exceptions assigned to this user (or unassigned if assignee is empty)."}},"description":"Exception count for a specific assignee."},"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}/exceptions:countByAssignee":{"get":{"summary":"Count Exceptions By Assignee","description":"Counts exceptions by assignee.\nReturns a list of assignees with their exception counts.\nUseful for workload distribution dashboards and identifying unassigned exceptions.","operationId":"CountExceptionsByAssignee","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountExceptionsByAssigneeResponse"}}}},"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":"filter","description":"Optional filter to apply before counting (same syntax as ListExceptions).\nUse this to count within a specific state, group, time range, etc.\nExample: \"state = PENDING\" to count only pending exceptions by assignee.\nExample: \"group = \\\"missing_values\\\"\" to count exceptions in missing_values group by assignee.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of assignees to return.\nIf unspecified, at most 50 assignees 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":"The page token from a previous CountExceptionsByAssignee call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}}
```

## Query Exception Insights

> Queries exception insights including MTTR and trends over time periods.\
> Useful for dashboards and analytics to understand exception patterns and resolution times.\
> This is a custom method for analytics/reporting, not a standard Get operation.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1QueryExceptionInsightsResponse":{"type":"object","properties":{"mttr_seconds":{"type":"number","format":"double","description":"Mean time to resolution in seconds across all resolved exceptions in the time window.\nThis is the average time from exception creation to resolution.\nReturns 0 if no exceptions were resolved in the period.","readOnly":true}},"description":"Response to a query exception insights request."},"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":{}},"ExceptionManagerServiceQueryExceptionInsightsBody":{"type":"object","properties":{"time_window":{"$ref":"#/components/schemas/v1TimeWindow"}},"description":"Request to query exception insights.","required":["time_window"]},"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."},"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`."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:queryInsights":{"post":{"summary":"Query Exception Insights","description":"Queries exception insights including MTTR and trends over time periods.\nUseful for dashboards and analytics to understand exception patterns and resolution times.\nThis is a custom method for analytics/reporting, not a standard Get operation.","operationId":"QueryExceptionInsights","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1QueryExceptionInsightsResponse"}}}},"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/ExceptionManagerServiceQueryExceptionInsightsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Retry Exceptions

> Retries multiple exceptions in a single request.\
> Only PENDING exceptions are retried; RESOLVED and ARCHIVED exceptions are skipped.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1RetryExceptionsResponse":{"type":"object","description":"Response for retrying exceptions; no body."},"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":{}},"ExceptionManagerServiceRetryExceptionsBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"description":"The full resource names of the exceptions to retry.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}\nDuplicate names may be de-duplicated by the server."}},"description":"Request to retry multiple exceptions in one request.\nOnly PENDING exceptions are retried; RESOLVED and ARCHIVED exceptions are skipped.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:retry":{"post":{"summary":"Retry Exceptions","description":"Retries multiple exceptions in a single request.\nOnly PENDING exceptions are retried; RESOLVED and ARCHIVED exceptions are skipped.","operationId":"RetryExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1RetryExceptionsResponse"}}}},"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/ExceptionManagerServiceRetryExceptionsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Skip Exceptions

> Skips multiple exceptions in a single request.\
> Only PENDING exceptions are skipped; RESOLVED and ARCHIVED exceptions are ignored.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1SkipExceptionsResponse":{"type":"object","description":"Response for skipping exceptions; no body."},"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":{}},"ExceptionManagerServiceSkipExceptionsBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"description":"The full resource names of the exceptions to skip.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}\nDuplicate names may be de-duplicated by the server."}},"description":"Request to skip multiple exceptions in one request.\nOnly PENDING exceptions are skipped; RESOLVED and ARCHIVED exceptions are ignored.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:skip":{"post":{"summary":"Skip Exceptions","description":"Skips multiple exceptions in a single request.\nOnly PENDING exceptions are skipped; RESOLVED and ARCHIVED exceptions are ignored.","operationId":"SkipExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1SkipExceptionsResponse"}}}},"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/ExceptionManagerServiceSkipExceptionsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```

## Unarchive Exceptions

> Unarchives ARCHIVED exceptions back to PENDING state.\
> Use this to undo accidental archive operations.\
> Non-ARCHIVED exceptions are ignored.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UnarchiveExceptionsResponse":{"type":"object","properties":{"unarchived_count":{"type":"integer","format":"int32","description":"Number of exceptions transitioned from ARCHIVED to PENDING state."}},"description":"Response for unarchiving exceptions."},"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":{}},"ExceptionManagerServiceUnarchiveExceptionsBody":{"type":"object","properties":{"filter":{"type":"string","title":"Filter to apply before unarchiving. Filter is required as a safeguard to prevent unarchiving ALL exceptions in workspace.\nOnly ARCHIVED exceptions matching the filter will be unarchived and transitioned to PENDING state. Non-ARCHIVED exceptions are ignored by the implementation.\nAllowed fields: run, automation, create_time, group\nExample: \"automation = my-automation-id\" - Unarchives archived exceptions for an automation\nExample: \"group = my-group-id AND create_time < \\\"2025-01-01T00:00:00Z\\\"\" - Unarchives old archived exceptions in my-group-id group\nExample: \"run = run1_id OR run = run2_id\" - Unarchives archived exceptions for multiple runs"}},"description":"Request to unarchive exceptions.","required":["filter"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:unarchive":{"post":{"summary":"Unarchive Exceptions","description":"Unarchives ARCHIVED exceptions back to PENDING state.\nUse this to undo accidental archive operations.\nNon-ARCHIVED exceptions are ignored.","operationId":"UnarchiveExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UnarchiveExceptionsResponse"}}}},"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/ExceptionManagerServiceUnarchiveExceptionsBody"}}},"required":true},"tags":["Exceptions"]}}}}
```
