Exceptions

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

Get Exception

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

exception_idstringRequired

Responses

200

A successful response.

application/json

An exception that occurred during an automation run. Exceptions are raised by the interpreter and are analogous to Python exceptions. However, the Kognitos platform provides various mechanisms to resolve an exception and then resume the run. Automation runs are important business processes for our users, so the expectation is that every exception needs to be resolved even if the resolution involves manual steps or abandoning the automation run.

namestringOptional

runstringRequired

messagestringRequired

The exception message generated by the interpreter.

create_timestring · date-timeRead-onlyOptional

The timestamp of when the exception was created.

update_timestring · date-timeRead-onlyOptional

The timestamp of when the exception was last updated.

statestring · enumOptional

The state of an exception.

• EXCEPTION_STATE_UNSPECIFIED: The state is not specified.
• EXCEPTION_STATE_PENDING: The exception is pending resolution. This is the initial state when an exception is created. Transitions: On creation --> PENDING PENDING --> RESOLVED: Exception successfully resolved (run can continue) PENDING --> ARCHIVED: Exception archived without resolution (run abandoned)
• EXCEPTION_STATE_RESOLVED: The exception has been resolved. RESOLVED is a terminal state. Resolved exceptions are retained for historical records Transitions: PENDING --> RESOLVED: Exception resolved (run can continue)
• EXCEPTION_STATE_ARCHIVED: The exception has been archived. Archived exceptions are retained for historical records and audit purposes. Transitions: PENDING --> ARCHIVED: Exception archived without resolution (run abandoned) ARCHIVED --> PENDING: Exception unarchived (run can continue)

Default: EXCEPTION_STATE_UNSPECIFIEDPossible values:

automationstringRead-onlyOptional

descriptionstringRead-onlyOptional

A human-friendly description of the exception. Generated by the exception service. Recently created exceptions may not yet have a description.

groupstringOptional

Groups are used to categorize exceptions Currently support static groups: "missing_values", "user_system_error", "internal_error" Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error Format: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error In future, we may support dynamic groups. Empty string means the exception is not grouped.

resolution_guide_entrystringRead-onlyOptional

stagestring · enumOptional

AutomationStage represents the publication stage of an automation. This enum is shared across services that manage or execute automations.

• AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.
• AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.
• AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.

Default: AUTOMATION_STAGE_UNSPECIFIEDPossible values:

execution_idstringOptional

assigneestringOptional

resolverstringOptional

The entity that resolved this exception. Can be either a user (for manual resolutions) or an agent (for automatic resolutions). Format: users/{user} or agents/{agent} Note: No resource_reference is specified to avoid service dependencies and to support multiple resource types in a single field.

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id} HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "run": "text",
  "location": {
    "start_byte": "text",
    "end_byte": "text"
  },
  "message": "text",
  "create_time": "2026-03-12T11:49:24.955Z",
  "update_time": "2026-03-12T11:49:24.955Z",
  "state": "EXCEPTION_STATE_UNSPECIFIED",
  "automation": "text",
  "description": "text",
  "group": "text",
  "resolution_guide_entry": "text",
  "stage": "AUTOMATION_STAGE_UNSPECIFIED",
  "execution_id": "text",
  "extra": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "assignee": "text",
  "resolver": "text"
}

List Exceptions

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

Query parameters

page_sizeinteger · int32Optional

The maximum number of exceptions to return. The service may return fewer than this value. If unspecified, at most 50 exceptions will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation.

page_tokenstringOptional

The page token, received from a previous ListExceptions call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListExceptions must match the call that provided the page token.

skipinteger · int32Optional

The number of exceptions to skip before returning results.

filterstringOptional

The filter to apply to the list of exceptions. Follows Google AIP-160 filtering standard (https://google.aip.dev/160).

Supported Fields:

• state: Exception state (PENDING, RESOLVED, ARCHIVED)
• automation: Automation ID (exact match only)
• create_time: Exception creation timestamp (ISO 8601 format)
• group: Exception group (exact match only)
  • Use group = "value" to match a specific group
  • Use group = "" to match exceptions with no group assigned (ungrouped)
• run: Run ID (exact match only)
  • Use run = "run1_id" to match a specific run
  • Use run = "run1_id OR run2_id" to match multiple runs

Supported Operators:

• Comparison: =, !=, <, <=, >, >=
• Logical: AND, OR, NOT
• Grouping: ( )

State Values:

• PENDING or EXCEPTION_STATE_PENDING
• RESOLVED or EXCEPTION_STATE_RESOLVED
• ARCHIVED or EXCEPTION_STATE_ARCHIVED

Timestamp Format:

• ISO 8601 with Z suffix: "2025-01-01T00:00:00Z"
• ISO 8601 with offset: "2025-01-01T00:00:00+00:00"

Example Filters:

• "state = PENDING" - List only pending exceptions
• "state != RESOLVED" - List all non-resolved exceptions
• "automation = my-automation-id" - List exceptions for a specific automation
• "state = PENDING AND automation = my-automation-id" - Pending exceptions for an automation
• "state = PENDING OR state = ARCHIVED" - Pending or archived exceptions
• "NOT state = RESOLVED" - All non-resolved exceptions
• "create_time > "2025-01-01T00:00:00Z"" - Exceptions created after Jan 1, 2025
• "create_time >= "2025-01-01T00:00:00Z" AND create_time < "2025-02-01T00:00:00Z"" - January 2025 exceptions
• "(state = PENDING OR state = ARCHIVED) AND create_time > "2025-01-01T00:00:00Z"" - Recent unresolved exceptions
• "group = "missing_values"" - List exceptions in exactly the missing_values group
• "group = "missing_values" OR group = "user_system_error"" - List exceptions in multiple groups
• "group = """ - List ungrouped exceptions (no group assigned)
• "state = PENDING AND group = """ - List pending ungrouped exceptions
• "group != """ - List all exceptions that have a group assigned (any group)
• "run = run1_id OR run = run2_id" - List exceptions for multiple runs
• "run = run1_id" - List exceptions for a specific run

Responses

200

A successful response.

application/json

A response to a list exceptions request.

next_page_tokenstringOptional

A token to retrieve the next page of results. Pass this value in the page_token field in the subsequent call to ListExceptions to continue listing results. Will be empty when there are no more results.

total_sizeinteger · int32Optional

The total number of exceptions that match the given filter across all pages. This count is not affected by page_size or page_token parameters.

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "exceptions": [
    {
      "name": "text",
      "run": "text",
      "location": {
        "start_byte": "text",
        "end_byte": "text"
      },
      "message": "text",
      "create_time": "2026-03-12T11:49:24.955Z",
      "update_time": "2026-03-12T11:49:24.955Z",
      "state": "EXCEPTION_STATE_UNSPECIFIED",
      "automation": "text",
      "description": "text",
      "group": "text",
      "resolution_guide_entry": "text",
      "stage": "AUTOMATION_STAGE_UNSPECIFIED",
      "execution_id": "text",
      "extra": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "assignee": "text",
      "resolver": "text"
    }
  ],
  "next_page_token": "text",
  "total_size": 1
}

List Events

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

run_idstringRequired

agent_idstringRequired

Query parameters

page_sizeinteger · int32Optional

The maximum number of events to return. The service may return fewer than this value. If unspecified, at most 50 events will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation.

page_tokenstringOptional

The page token, received from a previous ListEvents call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListEvents must match the call that provided the page token.

filterstringOptional

The filter to apply to the list of events. Follows Google AIP-160 filtering standard (https://google.aip.dev/160).

Supported Fields:

• exception: Exception Id

Supported Operators:

• Comparison: =, !=
• Logical: AND, OR, NOT
• Grouping: ( )

Example Filters:

• "exception = "exc-123"" - Events for a specific exception
• "exception = "exc-123" OR exception = "exc-456"" - Events for multiple exceptions

Responses

200

A successful response.

application/json

A response to a list events request.

next_page_tokenstringOptional

A token to retrieve the next page of results. Pass this value in the page_token field in the subsequent call to ListEvents to continue listing results. Will be empty when there are no more results.

total_sizeinteger · int32Optional

The total number of events in the conversation thread across all pages. This count is not affected by page_size or page_token parameters.

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "events": [
    {
      "name": "text",
      "state": "STATE_UNSPECIFIED",
      "create_time": "2026-03-12T11:49:24.955Z",
      "update_time": "2026-03-12T11:49:24.955Z",
      "user_message": {
        "user": "text",
        "content": "text",
        "content_list": {
          "items": [
            {
              "text": "text",
              "file": {
                "remote": "text",
                "inline": {
                  "mime_type": "text",
                  "content": "Ynl0ZXM=",
                  "filename": "text"
                }
              }
            }
          ]
        }
      },
      "agent_message": {
        "content": "text"
      },
      "tool_call_request": {
        "tool_call_id": "text",
        "display_name": "text",
        "input": "text"
      },
      "tool_call_result": {
        "tool_call_id": "text",
        "result": "text"
      },
      "thinking": {
        "content": "text"
      },
      "system_message": {
        "content": "text"
      },
      "completion_response": {
        "content": "text",
        "error": "text"
      },
      "exception": "text"
    }
  ],
  "next_page_token": "text",
  "total_size": 1
}

Create Event

post

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

run_idstringRequired

agent_idstringRequired

Body

application/json

An event in a run conversation thread about an exception. Events form a timeline of interactions between users, AI agents, and the system.

namestringOptional

statestring · enumOptional

The state of an event.

• STATE_UNSPECIFIED: The state is not specified. This value is not used.
• STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.
• STATE_COMPLETE: The event fields are done being generated.

Default: STATE_UNSPECIFIEDPossible values:

create_timestring · date-timeRead-onlyOptional

The timestamp when the event was created.

update_timestring · date-timeRead-onlyOptional

The timestamp when the event was last updated.

exceptionstringOptional

Responses

200

A successful response.

application/json

An event in a run conversation thread about an exception. Events form a timeline of interactions between users, AI agents, and the system.

namestringOptional

statestring · enumOptional

The state of an event.

• STATE_UNSPECIFIED: The state is not specified. This value is not used.
• STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.
• STATE_COMPLETE: The event fields are done being generated.

Default: STATE_UNSPECIFIEDPossible values:

create_timestring · date-timeRead-onlyOptional

The timestamp when the event was created.

update_timestring · date-timeRead-onlyOptional

The timestamp when the event was last updated.

exceptionstringOptional

default

An unexpected error response.

application/json

post

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events

HTTPcURLJavaScriptPython

POST /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 401

{
  "name": "text",
  "state": "STATE_UNSPECIFIED",
  "user_message": {
    "user": "text",
    "content": "text",
    "content_list": {
      "items": [
        {
          "text": "text",
          "file": {
            "remote": "text",
            "inline": {
              "mime_type": "text",
              "content": "Ynl0ZXM=",
              "filename": "text"
            }
          }
        }
      ]
    }
  },
  "agent_message": {},
  "tool_call_request": {},
  "tool_call_result": {},
  "thinking": {},
  "system_message": {},
  "completion_response": {
    "content": "text",
    "error": "text"
  },
  "exception": "text"
}

{
  "name": "text",
  "state": "STATE_UNSPECIFIED",
  "create_time": "2026-03-12T11:49:24.955Z",
  "update_time": "2026-03-12T11:49:24.955Z",
  "user_message": {
    "user": "text",
    "content": "text",
    "content_list": {
      "items": [
        {
          "text": "text",
          "file": {
            "remote": "text",
            "inline": {
              "mime_type": "text",
              "content": "Ynl0ZXM=",
              "filename": "text"
            }
          }
        }
      ]
    }
  },
  "agent_message": {
    "content": "text"
  },
  "tool_call_request": {
    "tool_call_id": "text",
    "display_name": "text",
    "input": "text"
  },
  "tool_call_result": {
    "tool_call_id": "text",
    "result": "text"
  },
  "thinking": {
    "content": "text"
  },
  "system_message": {
    "content": "text"
  },
  "completion_response": {
    "content": "text",
    "error": "text"
  },
  "exception": "text"
}

Get Event

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

run_idstringRequired

agent_idstringRequired

event_idstringRequired

Responses

200

A successful response.

application/json

An event in a run conversation thread about an exception. Events form a timeline of interactions between users, AI agents, and the system.

namestringOptional

statestring · enumOptional

The state of an event.

• STATE_UNSPECIFIED: The state is not specified. This value is not used.
• STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.
• STATE_COMPLETE: The event fields are done being generated.

Default: STATE_UNSPECIFIEDPossible values:

create_timestring · date-timeRead-onlyOptional

The timestamp when the event was created.

update_timestring · date-timeRead-onlyOptional

The timestamp when the event was last updated.

exceptionstringOptional

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id} HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "state": "STATE_UNSPECIFIED",
  "create_time": "2026-03-12T11:49:24.955Z",
  "update_time": "2026-03-12T11:49:24.955Z",
  "user_message": {
    "user": "text",
    "content": "text",
    "content_list": {
      "items": [
        {
          "text": "text",
          "file": {
            "remote": "text",
            "inline": {
              "mime_type": "text",
              "content": "Ynl0ZXM=",
              "filename": "text"
            }
          }
        }
      ]
    }
  },
  "agent_message": {
    "content": "text"
  },
  "tool_call_request": {
    "tool_call_id": "text",
    "display_name": "text",
    "input": "text"
  },
  "tool_call_result": {
    "tool_call_id": "text",
    "result": "text"
  },
  "thinking": {
    "content": "text"
  },
  "system_message": {
    "content": "text"
  },
  "completion_response": {
    "content": "text",
    "error": "text"
  },
  "exception": "text"
}

Stream Events

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

run_idstringRequired

agent_idstringRequired

Responses

200

NDJSON stream of StreamEventsResponse objects (one JSON object per line)

application/x-ndjson

string · binaryOptional

default

An unexpected error response.

application/x-ndjson

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:stream

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:stream HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

binary

Cancel Generation

post

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

run_idstringRequired

agent_idstringRequired

Responses

200

A successful response.

application/json

objectOptional

Response for canceling ongoing event generation. Empty response. Reserved for future extensibility.

default

An unexpected error response.

application/json

post

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:cancelGeneration

HTTPcURLJavaScriptPython

POST /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:cancelGeneration HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}

List Exception Groups

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

Query parameters

page_sizeinteger · int32Optional

The maximum number of groups to return. Note: Since groups are static and typically small in number, pagination is not strictly necessary but included for AIP compliance.

page_tokenstringOptional

The page token from a previous ListExceptionGroups call.

Responses

200

A successful response.

application/json

Response containing available exception groups.

next_page_tokenstringOptional

Token to retrieve the next page of results. Empty when there are no more results.

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "groups": [
    {
      "name": "text",
      "title": "text",
      "description": "text",
      "suggested_action": "text",
      "default_assignee": "text"
    }
  ],
  "next_page_token": "text"
}

Count Exceptions By Group

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

Query parameters

filterstringOptional

Optional filter to apply before counting (same syntax as ListExceptions). Use this to count within a specific state, automation, time range, etc. Example: "state = PENDING" to count only pending exceptions by group.

page_sizeinteger · int32Optional

The maximum number of groups to return. If unspecified, at most 50 groups will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_tokenstringOptional

The page token from a previous CountExceptionsByGroup call.

Responses

200

A successful response.

application/json

Response containing exception counts by group.

next_page_tokenstringOptional

Token to retrieve the next page of results. Empty when there are no more results.

total_sizeinteger · int32Optional

Total number of groups with exceptions (across all pages). Respects the filter from the request.

total_exception_countinteger · int32Optional

Total count of all exceptions across all groups. Respects the filter from the request. This is the sum of all counts in group_counts (across all pages). Useful for displaying summary statistics like "110 total exceptions across 3 groups".

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByGroup

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByGroup HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "group_counts": [
    {
      "group": {
        "name": "text",
        "title": "text",
        "description": "text",
        "suggested_action": "text",
        "default_assignee": "text"
      },
      "count": 1
    }
  ],
  "next_page_token": "text",
  "total_size": 1,
  "total_exception_count": 1
}

Count Exceptions By Automation

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

Query parameters

filterstringOptional

Optional filter to apply before counting (same syntax as ListExceptions). Use this to count within a specific state, group, time range, etc. Example: "state = PENDING" to count only pending exceptions by automation. Example: "group = "missing_values"" to count exceptions in missing_values group by automation.

page_sizeinteger · int32Optional

The maximum number of automations to return. If unspecified, at most 50 automations will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_tokenstringOptional

The page token from a previous CountExceptionsByAutomation call.

Responses

200

A successful response.

application/json

Response containing exception counts by automation.

next_page_tokenstringOptional

Token to retrieve the next page of results. Empty when there are no more results.

total_sizeinteger · int32Optional

Total number of automations with exceptions (across all pages). Respects the filter from the request.

total_exception_countinteger · int32Optional

Total count of all exceptions across all automations. Respects the filter from the request. This is the sum of all counts in automation_counts (across all pages). Useful for displaying summary statistics like "500 total exceptions across 25 automations".

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByAutomation

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByAutomation HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "automation_counts": [
    {
      "automation": "text",
      "count": 1
    }
  ],
  "next_page_token": "text",
  "total_size": 1,
  "total_exception_count": 1
}

Get Guide Entry

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

guide_entry_idstringRequired

Responses

200

A successful response.

application/json

namestringOptional

contentstringOptional

Markdown-formatted entry content Deprecated: Use resolution_steps and resolution_code instead.

source_exceptionstringOptional

source_runstringOptional

create_timestring · date-timeRead-onlyOptional

update_timestring · date-timeRead-onlyOptional

delete_timestring · date-timeRead-onlyOptional

The time when this guide entry was soft-deleted. If not set, the entry has not been deleted. Soft-deleted entries are not physically removed but marked as deleted. Always set the state to STATE_ARCHIVED whenever the entry is soft-deleted.

titlestringOptional

Title of the guide entry Marked as optional for backwards compatibility. Can be set when creating or updating the guide entry.

automationstringRead-onlyOptional

root_causestringOptional

Root cause analysis explaining why the exception occurred. This provides technical context about what caused the issue. Marked as optional for backwards compatibility.

statestring · enumOptional

The state of a guide entry.

• STATE_UNSPECIFIED: The state is not specified.
• STATE_PENDING_APPROVAL: The guide entry is pending approval.
• STATE_APPROVED: The guide entry is approved.
• STATE_REJECTED: The guide entry is rejected.
• STATE_ARCHIVED: The guide entry is archived.

Default: STATE_UNSPECIFIEDPossible values:

versionstringRead-onlyOptional

resolution_stepsstringOptional

Human-readable explanation of the resolution action and steps. GitHub Flavored Markdown (GFM) formatted.

Resolution Field Guidelines:

• At least one of resolution_steps, resolution_code, or resolution_notes should be present for the guide entry to be useful. Entries with none of these fields are considered incomplete.
• These fields are complementary and can be used together:
  • resolution_steps: The primary resolution instructions
  • resolution_code: Supporting code examples
  • resolution_notes: Additional context or caveats

resolution_codestringOptional

Example code illustrating how this type of exception was resolved. Serves as a reference when handling similar exceptions in future runs. May require adaptation based on specific context and should not be applied verbatim.

resolution_notesstringOptional

Additional notes, caveats, or context about the resolution. GitHub Flavored Markdown (GFM) formatted. Use for edge cases, warnings, or supplementary information.

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id} HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "content": "text",
  "source_exception": "text",
  "source_run": "text",
  "create_time": "2026-03-12T11:49:24.955Z",
  "update_time": "2026-03-12T11:49:24.955Z",
  "delete_time": "2026-03-12T11:49:24.955Z",
  "title": "text",
  "automation": "text",
  "root_cause": "text",
  "state": "STATE_UNSPECIFIED",
  "version": "text",
  "resolution_steps": "text",
  "resolution_code": "text",
  "resolution_notes": "text"
}

List Guide Entries

get

Authorizations

BearerAuth

AuthorizationstringRequired

Personal Access Token.

Path parameters

organization_idstringRequired

workspace_idstringRequired

automation_idstringRequired

Query parameters

page_sizeinteger · int32Optional

The maximum number of guide entries to return. The service may return fewer than this value. If unspecified, at most 50 guide entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Note: These limits are enforced by server-side validation.

page_tokenstringOptional

The page token, received from a previous ListGuideEntries call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListGuideEntries must match the call that provided the page token.

show_deletedbooleanOptional

If true, soft-deleted guide entries will be included in the results. Deleted entries have delete_time set. Defaults to false (deleted entries are filtered out).

filterstringOptional

The filter to apply to the list of guide entries. Follows Google AIP-160 filtering standard (https://google.aip.dev/160).

Supported Fields:

• title: Guide entry title (partial match only)
• resolution_steps: Resolution steps content (partial match only)
• resolution_code: Resolution code content (partial match only)
• resolution_notes: Resolution notes content (partial match only)
• automation: Automation ID (exact match only)
• create_time: Guide entry creation timestamp (ISO 8601 format)
• update_time: Guide entry update timestamp (ISO 8601 format)
• content: (DEPRECATED) Guide entry content - use resolution_steps, resolution_code, or resolution_notes instead

Supported Operators:

• Comparison: =, !=, <, <=, >, >=
• Logical: AND, OR, NOT
• Grouping: ( )
• Partial Match: contains

Example Filters:

• "title contains 'My Guide Entry'" - List guide entries with title containing "My Guide Entry"
• "resolution_steps contains 'restart'" - List guide entries with resolution steps containing "restart"
• "resolution_code contains 'retry'" - List guide entries with resolution code containing "retry"
• "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.
• "automation = my-automation-id or automation = another-automation-id" - List guide entries for specific automations.
• "create_time > "2025-01-01T00:00:00Z"" - Guide entries created after Jan 1, 2025
• "update_time >= "2025-01-01T00:00:00Z" AND update_time < "2025-02-01T00:00:00Z"" - January 2025 guide entries
• "(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

Responses

200

A successful response.

application/json

next_page_tokenstringOptional

A token to retrieve the next page of results. Pass this value in the page_token field in the subsequent call to ListGuideEntries to continue listing results. Will be empty when there are no more results.

total_sizeinteger · int32Optional

The total number of guide entries across all pages. This count respects the show_deleted parameter but is not affected by page_size or page_token.

default

An unexpected error response.

application/json

get

/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries

HTTPcURLJavaScriptPython

GET /api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries HTTP/1.1
Host: app.us-1.kognitos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "guide_entries": [
    {
      "name": "text",
      "content": "text",
      "source_exception": "text",
      "source_run": "text",
      "create_time": "2026-03-12T11:49:24.955Z",
      "update_time": "2026-03-12T11:49:24.955Z",
      "delete_time": "2026-03-12T11:49:24.955Z",
      "title": "text",
      "automation": "text",
      "root_cause": "text",
      "state": "STATE_UNSPECIFIED",
      "version": "text",
      "resolution_steps": "text",
      "resolution_code": "text",
      "resolution_notes": "text"
    }
  ],
  "next_page_token": "text",
  "total_size": 1
}