---
title: "CreateQueryCommandClassification"
method: POST
path: "/v1/namespaces/{tenant_meta.namespace}/queries/command-classification"
tags: ["QueryCommandClassificationService"]
---

# CreateQueryCommandClassification

`POST /v1/namespaces/{tenant_meta.namespace}/queries/command-classification`

## Request

- Base URL: `https://api.endorlabs.com`
- URL: `https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/queries/command-classification`
- Auth: none declared

Labels a shell command an AI coding agent proposed to run.

## Path parameters

- `tenant_meta.namespace` string, required

## Request body

- QueryCommandClassificationServiceCreateQueryCommandClassificationBody: QueryCommandClassification labels a shell command an AI coding agent proposed to run: benign, suspicious, or review. The judgment is made on the command's own security intent and effect, with no pattern behind it, which is what lets it stand in for the CMD_LINE regexes rather than only second-guess them. The caller sends the command and nothing else. The prompt, the model, and the judging rubric all live on the server, which is what keeps this endpoint different in kind from AIRequest: a caller cannot choose the model or steer the prompt, so the capability it grants is "classify a command", not "run inference on this tenant's account". That is the same split that lets AIQuery be safe for read-only callers.
  - `meta` V1Meta: 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.
  - `spec` V1QueryCommandClassificationSpec: Spec carries the one input and the judgment, plus what the call cost. The caller sends command and reads everything else back.
    - `ai_request_uuid` string: Uuid of the AIRequest row this classification was billed as. That row carries CompletionUsage and the credit accounting, so it is the join key for deriving what a judgment cost; the caller stores the uuid rather than a currency figure, which would go stale on a price change.
    - `cached_tokens` integer: Tokens served from the provider's prompt cache. The rubric is a standing prefix, so this reports whether it is actually being cached.
    - `command` string, required: The command to judge, as the hook observed it. It is judged on its own security intent and effect: no policy, pattern, or action tier is sent, because there may not have been one.
    - `completion_tokens` integer: Tokens the label itself cost. Small by design: the answer is one JSON object, so a large value here means the model is explaining itself.
    - `confidence` number, float: Confidence in the label, 0.0 to 1.0. Advisory only: it is reported so a threshold can be calibrated against real data rather than guessed.
    - `deployment_context` string[]: Free-text lines describing the caller's deployment: which hosts are the organisation's own, which registries are sanctioned, which credentials are expected to be present on the machine. They fill the trust anchors the rubric names as deployment-supplied and ships empty, and they are appended AFTER the rubric so the rubric stays a byte-identical standing prefix the provider can serve from its cache. This is the one input besides the command, and it is still not a prompt: the caller supplies facts about its environment, not instructions to the model. It comes from the tenant's own auto-mode policy rather than from the hook's own reading of the machine.
    - `label` 'LABEL_UNSPECIFIED' | 'LABEL_BENIGN' | 'LABEL_SUSPICIOUS' | 'LABEL_REVIEW': Label is the judgment on one command. Each value maps to an action the agent hook already has. - LABEL_UNSPECIFIED: No label was produced. Never treat this as a benign result. - LABEL_BENIGN: The command shows nothing concerning on its own. - LABEL_SUSPICIOUS: The command shows something concerning. - LABEL_REVIEW: The decision turns on context the model does not have, so the command belongs in front of the user rather than being cleared or blocked.
    - `model` string: The model that produced the label, for attribution and for comparing one model against another.
    - `prompt_tokens` integer: Tokens the classification consumed. The caller runs this in the critical path of a developer's agent, so it is told what the call cost.
    - `reason` string: One clause naming the concrete thing seen in the command.
    - `rubric_version` string: Version of the rubric the label was produced under. A label recorded today is not comparable to one recorded after the rubric changed, so the caller is told which one judged its command rather than having to assume.
  - `tenant_meta` object: The tenant metadata restricts access to a specific tenant.
  - `uuid` string: The uuid of the resource.

## Response `200`

A successful response.

- V1QueryCommandClassification: QueryCommandClassification labels a shell command an AI coding agent proposed to run: benign, suspicious, or review. The judgment is made on the command's own security intent and effect, with no pattern behind it, which is what lets it stand in for the CMD_LINE regexes rather than only second-guess them. The caller sends the command and nothing else. The prompt, the model, and the judging rubric all live on the server, which is what keeps this endpoint different in kind from AIRequest: a caller cannot choose the model or steer the prompt, so the capability it grants is "classify a command", not "run inference on this tenant's account". That is the same split that lets AIQuery be safe for read-only callers.
  - `meta` V1Meta: 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.
  - `spec` V1QueryCommandClassificationSpec: Spec carries the one input and the judgment, plus what the call cost. The caller sends command and reads everything else back.
    - `ai_request_uuid` string: Uuid of the AIRequest row this classification was billed as. That row carries CompletionUsage and the credit accounting, so it is the join key for deriving what a judgment cost; the caller stores the uuid rather than a currency figure, which would go stale on a price change.
    - `cached_tokens` integer: Tokens served from the provider's prompt cache. The rubric is a standing prefix, so this reports whether it is actually being cached.
    - `command` string, required: The command to judge, as the hook observed it. It is judged on its own security intent and effect: no policy, pattern, or action tier is sent, because there may not have been one.
    - `completion_tokens` integer: Tokens the label itself cost. Small by design: the answer is one JSON object, so a large value here means the model is explaining itself.
    - `confidence` number, float: Confidence in the label, 0.0 to 1.0. Advisory only: it is reported so a threshold can be calibrated against real data rather than guessed.
    - `deployment_context` string[]: Free-text lines describing the caller's deployment: which hosts are the organisation's own, which registries are sanctioned, which credentials are expected to be present on the machine. They fill the trust anchors the rubric names as deployment-supplied and ships empty, and they are appended AFTER the rubric so the rubric stays a byte-identical standing prefix the provider can serve from its cache. This is the one input besides the command, and it is still not a prompt: the caller supplies facts about its environment, not instructions to the model. It comes from the tenant's own auto-mode policy rather than from the hook's own reading of the machine.
    - `label` 'LABEL_UNSPECIFIED' | 'LABEL_BENIGN' | 'LABEL_SUSPICIOUS' | 'LABEL_REVIEW': Label is the judgment on one command. Each value maps to an action the agent hook already has. - LABEL_UNSPECIFIED: No label was produced. Never treat this as a benign result. - LABEL_BENIGN: The command shows nothing concerning on its own. - LABEL_SUSPICIOUS: The command shows something concerning. - LABEL_REVIEW: The decision turns on context the model does not have, so the command belongs in front of the user rather than being cleared or blocked.
    - `model` string: The model that produced the label, for attribution and for comparing one model against another.
    - `prompt_tokens` integer: Tokens the classification consumed. The caller runs this in the critical path of a developer's agent, so it is told what the call cost.
    - `reason` string: One clause naming the concrete thing seen in the command.
    - `rubric_version` string: Version of the rubric the label was produced under. A label recorded today is not comparable to one recorded after the rubric changed, so the caller is told which one judged its command rather than having to assume.
  - `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 the resource.

## 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/queries/command-classification/post.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)