--- title: "ListAgentHookPolicyDefinitions" method: GET path: "/v1/namespaces/{tenant_meta.namespace}/agent-hook-policy-definitions" tags: ["AgentHookPolicyDefinitionService"] --- # ListAgentHookPolicyDefinitions `GET /v1/namespaces/{tenant_meta.namespace}/agent-hook-policy-definitions` ## Request - Base URL: `https://api.endorlabs.com` - URL: `https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/agent-hook-policy-definitions` - Auth: none declared Lists all AgentHookPolicyDefinitions visible in a namespace. ## Path parameters - `tenant_meta.namespace` string, required ## Query parameters - `list_parameters.filter` string - `list_parameters.page_token` integer - `list_parameters.page_size` integer - `list_parameters.action` string - `list_parameters.mask` string - `list_parameters.traverse` boolean - `list_parameters.sort.path` string - `list_parameters.sort.order` 'SORT_ENTRY_ORDER_UNSPECIFIED' | 'SORT_ENTRY_ORDER_ASC' | 'SORT_ENTRY_ORDER_DESC' - `list_parameters.count` boolean - `list_parameters.group.aggregation_paths` string - `list_parameters.group.show_aggregation_uuids` boolean - `list_parameters.group.unique_count_paths` string - `list_parameters.group.unique_value_paths` string - `list_parameters.ci_run_uuid` string - `list_parameters.page_id` string - `list_parameters.group_by_time.aggregation_paths` string - `list_parameters.group_by_time.show_aggregation_uuids` boolean - `list_parameters.group_by_time.interval` 'GROUP_BY_TIME_INTERVAL_UNSPECIFIED' | 'GROUP_BY_TIME_INTERVAL_YEAR' | 'GROUP_BY_TIME_INTERVAL_QUARTER' | 'GROUP_BY_TIME_INTERVAL_MONTH' | 'GROUP_BY_TIME_INTERVAL_WEEK' | 'GROUP_BY_TIME_INTERVAL_DAY' | 'GROUP_BY_TIME_INTERVAL_HOUR' | 'GROUP_BY_TIME_INTERVAL_MINUTE' | 'GROUP_BY_TIME_INTERVAL_SECOND' - `list_parameters.group_by_time.group_size` integer - `list_parameters.group_by_time.start_time` string, date-time - `list_parameters.group_by_time.end_time` string, date-time - `list_parameters.group_by_time.mode` string - `list_parameters.group_by_time.aggregation_value_field` string - `list_parameters.group_by_time.aggregation_operator` string - `list_parameters.disable_pagination` boolean ## Response `200` A successful response. - V1ListAgentHookPolicyDefinitionsResponse: Response to the request to list agent hook policy definitions. - `count_response` V1CountResponse: Response to a list count request. - `count` integer: Number of objects matching the given list parameters. - `group_response` V1GroupResponse: Response to a list group request. - `groups` object: Map indexed by values of the fields specified in aggregation_paths, for example, {"[{"key":"meta.kind","value":"Project"}]": { "aggregation_count": { "count": 1649 } } }. - `list` V1ListAgentHookPolicyDefinitionsResponseList - `objects` V1AgentHookPolicyDefinition[] - `meta` V1Meta, required: Common fields for all Endor Labs resources. - `annotations` object: Annotations can be used to attach metadata to a resource message. Annotation values can be small or large, structured or unstructured, and may include characters not permitted by labels. The keys may contain alphanumerics, underscores (_), dots (.) and dashes (-). The values of an annotation must be 16384 bytes or smaller. - `create_time` string, date-time: Time the resource was created. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `created_by` string: Name and authentication source of the user who created the object, for example, ewok@endor.ai@google@api-key. - `description` string: Resource description. Must be less than 1024 bytes. - `index_data` V1IndexData: IndexData is used to index the resource for search. It's an internal object. - `data` string[] - `search_score` number, float: search_score is the score of the resource for search. Internal use only. - `tenant` string - `will_be_deleted_at` string, date-time: Time that the resource will be deleted. - `kind` string: Resource kind, for example, HelloResponse. Auto-generated using the protobuf message proto.MessageName().Name(). - `name` string, required: Resource name. Must be 63 characters or less. - `parent_kind` string: Parent object resource kind, for example, Project. - `parent_uuid` string: Parent object UUID. - `references` object: Map of objects referenced in a query API. - `tags` string[]: List of tags attached to the resource. Tags can be used to select objects and to find collections of objects that satisfy certain conditions. A tag must be 255 characters or less. - `update_time` string, date-time: Time the resource was last updated. Note: Updated on all create/patch/delete operations. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `updated_by` string: Name and authentication source of the last user who updated the object, for example, vulnerabilityingestor@endor.ai@x509. - `upsert_time` string, date-time: Time the resource was last upserted. Note: create_time is only set the first time the resource is created. upsert_time is set every time the resource is upseted. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `version` string: Message version. - `propagate` boolean: Object can be propagated to child namespaces. Global objects are visible to all namespaces. - `spec` V1AgentHookPolicyDefinitionSpec - `policy` V1AgentHookPolicy: AgentHookPolicy describes a policy to apply when agent hook events match a given activity. When the activity matches, the action (e.g. feedback, block, alert) is applied. - `action` V1AgentHookAction: Action describes how to match the activity with the policy and what to do when it matches. - `alert` V1AlertAction: AlertAction records an alert with a message (e.g. for audit). - … - `ask` V1AskAction: AskAction allows asking the user with a message. - … - `auto` V1AutoAction: AutoAction hands the decision on a matched command to the LLM judge: the command is judged on its own security intent and effect, and the label that comes back is the decision — benign allows, review asks, suspicious blocks. It carries no message on purpose. The agent sees the model's own reason, naming the concrete thing it saw, and a policy-authored string would either be ignored or contradict it. The evaluator converts a matched AUTO policy into a plain ask or block carrying that reason before the verdict is computed, so the verdict is still read off ordinary action kinds. Valid only on cmd_line activities, with either match type, and never on a POLICY_INTENT_GOVERNANCE policy. On an ALLOWLIST the permitted set acts as a prefilter: a listed command never reaches the judge, and one outside it is judged rather than refused outright. Requires an endorctl new enough to know the field. An older client drops it (maniprest unmarshals with DiscardUnknown), is left with an empty action kind, and allows — so switching a policy to AUTO silently loses enforcement of that policy on clients below the minimum version. - `block` V1BlockAction: BlockAction blocks the activity and shows a message. - … - `feedback` V1FeedbackAction: FeedbackAction prompts the user with a message without blocking. - … - `match_type` 'MATCH_TYPE_UNSPECIFIED' | 'MATCH_TYPE_BLOCKLIST' | 'MATCH_TYPE_ALLOWLIST': We may want to trigger when the activity matches the patterns in the policy (blocklist) or alternatively when the activity does not match the patterns in the policy (allowlist). - `activity` V1AgentHookActivity: Activity describes what kind of hook activity the policy applies to. - `auto_mode` V1AutoModeActivity: AutoModeActivity turns LLM command judging on for a namespace and says which commands reach the judge. It is an activity kind rather than a resource of its own so that it inherits the AgentHookPolicyDefinition machinery: namespace propagation, name-based deduplication, the JSONL policy-file cache, enabled, and scope. It never produces a match of its own. It is read before the per-policy loop to decide which commands are judged, and a match the judge raises is a CMD_LINE match attributed to this policy. The model stays server-owned: the policy carries no model name and no prompt, only deployment_context. EXACTLY ONE applies to an event — the most specifically scoped candidate, with the policy name breaking an equal rank — and it supplies the whole configuration. They are not unioned, unlike secrets_check or malware_check, because a mode is not a finding: OR is monotone, so nothing at a narrower scope could ever turn a setting back off. A policy that loses is named in a warning, stays enabled and listed, and does nothing. - … - `cmd_line` V1CmdLineActivity: CmdLineActivity matches command-line execution by regex patterns. - … - `dependency_risk` V1DependencyRiskActivity: DependencyRiskActivity checks the dependencies an event introduces (from an install command or a manifest/lockfile edit) against Endor's vulnerability data. Matching the activity means running the check; the verdict comes from the lookup, not from the policy config. - … - `file_access` V1FileAccessActivity: FileAccessActivity matches file access by operation and path patterns. - … - `malware_check` V1MalwareCheckActivity: MalwareCheckActivity runs Endor's malware lookup against the packages in a package-install command (a cmd_line event). It carries no regex matchers: matching the activity means running the check, and the block/allow verdict comes from the malware feed (MALWARE-status, non-contested records), not from the policy config. - … - `mcp_server` V1McpServerActivity: McpServerActivity matches MCP servers by name patterns and/or score thresholds. Match logic: configured branches are AND'd — when both server_name_matchers and score predicates are set, both must hold; when only one is set, only that one must hold; if neither is set, the activity never matches. Within the score branch, score_at_or_below and every set field of dimension_at_or_below are OR'd: any single satisfied threshold fires the branch. This is server-level matching; for per-tool-call matching, use McpToolCallActivity. - … - `mcp_tool_call` V1McpToolCallActivity: McpToolCallActivity matches tool calls to a specific MCP server and tool. - … - `secrets_check` V1SecretsCheckActivity: SecretsCheckActivity runs Endor's secret detection over file content (the proposed content of a write/edit, or a file read scanned from disk). Matching the activity means running the scan; the verdict comes from the findings, not from the policy config. - … - `session` V1SessionActivity: SessionActivity matches sessions by posture predicates over SessionHook fields and the captured AgentConfigSnapshot. Sessions have no stable name, so matching uses field predicates instead of name regexes. Each sub-message is optional; if set, all its predicates are AND'd. Sub-messages are also AND'd with each other. Predicates that target AgentConfigSnapshot evaluate across repository / user / enterprise levels (any-level satisfies). MCP-server-related criteria intentionally live on McpServerActivity, not here. - … - `skill` V1SkillActivity: SkillActivity matches skills by name patterns and/or score thresholds. Match logic: configured branches are AND'd — when both name_matchers and score predicates are set, both must hold for the match to fire; when only one is set, only that one must hold; if neither is set, the activity never matches. Within the score branch, score_at_or_below and every set field of dimension_at_or_below are OR'd: any single satisfied threshold fires the branch. When score predicates are set but no SkillMeta is available for the skill, the score branch is configured-but-cannot-fire, failing the AND with the name branch (fail-safe). - … - `tool_sandbox` V1ToolSandboxActivity: ToolSandboxActivity matches runtime sandbox state on a tool-call event. Values in each repeated field are OR'd. Configured fields are AND'd, and an excluded reason vetoes a match. Exclusions alone and empty activities never match. Unspecified and not-applicable postures do not satisfy posture matches. - … - `enabled` boolean: Whether this policy is active. - `intent` 'POLICY_INTENT_UNSPECIFIED' | 'POLICY_INTENT_RISK' | 'POLICY_INTENT_GOVERNANCE': PolicyIntent says what kind of rule a policy encodes, and so whether the LLM command judge may rule on its matches. Only cmd_line policies are judged, so today the intent changes behavior only on a cmd_line policy. - POLICY_INTENT_UNSPECIFIED: Read as POLICY_INTENT_RISK, so a policy that never sets the field keeps the behavior it had before the field existed. - POLICY_INTENT_RISK: The policy is a risk assessment. A judge scope may hand its matches to the judge, and the label can release, ask about, or block the command. - POLICY_INTENT_GOVERNANCE: The policy is an organisational rule, for example "installs go through the package firewall". A verdict on how risky the command is answers a question the rule does not ask, so no judge scope hands its matches to the judge. Its own action is final: no label releases it, and no label escalates it. Not valid with the AUTO action, which hands the decision to the judge. - `inventory_classification` 'INVENTORY_CLASSIFICATION_UNSPECIFIED' | 'INVENTORY_CLASSIFICATION_ALLOW' | 'INVENTORY_CLASSIFICATION_BLOCK' | 'INVENTORY_CLASSIFICATION_SUSPICIOUS' | 'INVENTORY_CLASSIFICATION_MALICIOUS': InventoryClassification declares the classification a policy assigns to a matched MCP server or skill when it fires. UNSPECIFIED means the policy plays no role in inventory classification (e.g. a session, file-access, or cmd-line policy, or an MCP/skill policy whose author only wants the per-event action). - `name` string: Name of the policy. - `scope` V1AgentHookPolicyScope: AgentHookPolicyScope restricts a policy to a subset of events by matching against per-event identity carried on AgentHookEvent.Spec (repository, user). Scope is evaluated once, before activity-kind matching, so it applies uniformly to all activity kinds. Match logic: an unset scope (or a scope with no matchers set) applies to every event. When set, configured matcher branches are AND'd — every set branch must produce a hit; within a branch the regexes are OR'd (any one matching satisfies the branch); an empty branch is ignored. A scope miss makes the policy a no-op for the event for both blocklist and allowlist match types (the policy simply does not apply). - `repository_matchers` string[]: Regex matchers for the repository from AgentHookEvent.Spec.repository (e.g. "github\\.com/acme/.*", ".*-infra$"). OR'd among themselves. - `user_matchers` string[]: Regex matchers for the user/account from AgentHookEvent.Spec.user (e.g. "alice", "svc-.*", ".*@example\\.com"). "Account" in the ticket maps to this per-session user identity; there is no separate account entity. OR'd among themselves. - `system` boolean: Whether this is a system-defined policy (vs user-defined). - `tenant_meta` V1TenantMeta: Tenant related data for the tenant containing the resource. - `namespace` string, required: Namespaces are a way to organize organizational units into virtual groupings of resources. Namespaces must be a fully qualified name, for example, the child namespace of namespace "endor.prod" called "app" is called "endor.prod.app". - `uuid` string: The UUID of an AgentHookPolicyDefinition. - `response` V1ListResponse: Response to a list request. - `next_page_id` string: The UUID of last message retrieved. - `next_page_token` integer: Pagination token that can be used to retrieve the next page of results. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-11-03** `4acd9fe15140`: 1 info - endpoint added [Operation history](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference/changes/v1/namespaces/:tenant_meta.namespace/agent-hook-policy-definitions/get.md) --- [API](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference.md) - [All operations](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference/revisions/9c1a64674369?raw)