--- title: "CreateAIRequest" method: POST path: "/v1/namespaces/{tenant_meta.namespace}/ai-requests" tags: ["AIRequestService"] --- # CreateAIRequest `POST /v1/namespaces/{tenant_meta.namespace}/ai-requests` ## Request - Base URL: `https://api.endorlabs.com` - URL: `https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/ai-requests` - Auth: none declared Creates an AIRequest. ## Path parameters - `tenant_meta.namespace` string, required ## Request body - AIRequestServiceCreateAIRequestBody: Implements qi request by interacting with the LLM API. - `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. - `spec` V1AIRequestSpec - `ai_feature` 'AI_FEATURE_UNSPECIFIED' | 'AI_FEATURE_SECURITY_REVIEW' | 'AI_FEATURE_AI_SAST' | 'AI_FEATURE_AIFP_EVALUATOR' | 'AI_FEATURE_LICENSE_EXTRACTION' | 'AI_FEATURE_MODEL_DISCOVERY' | 'AI_FEATURE_MODEL_METADATA_EXTRACTION' | 'AI_FEATURE_SKILL_SCORING' | 'AI_FEATURE_MCP_RISK_EVALUATION' | 'AI_FEATURE_AI_SAST_CONTEXT_SUMMARY' | 'AI_FEATURE_AGENT_POLICY_CMD_CLASSIFICATION' | 'AI_FEATURE_MALWARE_ANALYSIS': AIFeature identifies which AI feature is making the request. This is used for metrics, billing, and feature tracking. - AI_FEATURE_AI_SAST_CONTEXT_SUMMARY: AI SAST per-project context summarization that grounds segment prompts. - AI_FEATURE_AGENT_POLICY_CMD_CLASSIFICATION: Agent-governance adjudication of a command an agent hook policy flagged. - AI_FEATURE_MALWARE_ANALYSIS: Malware analysis of a published package version (ported sr-malware-detection LLM signals). - `byok` boolean: Deprecated: read credential_class instead. Still written, derived from it, so readers have one release to move. Indicates the request was served through customer-provided (bring your own key) provider credentials, which bill the customer's provider account and do not consume platform credits. - `credential_class` 'AI_CREDENTIAL_CLASS_UNSPECIFIED' | 'AI_CREDENTIAL_CLASS_PLATFORM' | 'AI_CREDENTIAL_CLASS_BYOK': AICredentialClass names the provider account an AI request billed against. It supersedes the byok boolean, which cannot name a third kind of account and cannot say which of a tenant's keys served a request. The value names carry a constraint. Lowercased and stripped of the AI_CREDENTIAL_CLASS_ prefix, each one must equal the credential-class label value the LLM metrics use, so a stored record and a metric series never name the same account differently. A rename breaks that pairing silently. - AI_CREDENTIAL_CLASS_UNSPECIFIED: No class was assigned, so the record predates credential classification. - AI_CREDENTIAL_CLASS_PLATFORM: Endor's own provider account served the request. - AI_CREDENTIAL_CLASS_BYOK: The tenant's own provider account served the request, reached through one of their AI provider keys. - `credential_ref` string: The uuid of the AI provider key that served the request, empty unless the credential class is BYOK. The key's endpoint is a secure field and stays redacted on every read, so this reference is the indirection to it: it identifies the customer account that billed the request without widening what is queryable. - `input` SpecInput, required: Input message for the AI request. - `max_output_tokens` integer: MaxOutputTokens is the maximum number of tokens that the agent will output. - `messages` SpecMessage[]: The messages of the AI request. - `role` 'ROLE_UNSPECIFIED' | 'ROLE_SYSTEM' | 'ROLE_USER' | 'ROLE_ASSISTANT' | 'ROLE_TOOLS', required - `text` string - `tool_calls` SpecToolCall[]: The tool calls of the message. This is only present if the role is ROLE_TOOLS. This is the list of tools that the LLM needs to call. - `function` ToolCallToolCallFunction - `arguments` object: The arguments of the tool. - `description` string: The description of the tool. - `name` string: The name of the tool. - `results` object: The results of the tool. - `id` string, required: The id of the tool call. - `model` string, required: The model which will be used to generate the response of the AI request. - `response_format` InputResponseFormat: The response format of the message. - `description` string: The description of the response format. - `json_schema` object: The JSON schema of the response format. - `name` string: The name of the response format. - `strict` boolean: Whether the response format is strict. - `temperature` number, float: temperature of the AI request. - `thinking_level` 'THINKING_LEVEL_UNSPECIFIED' | 'THINKING_LEVEL_AUTO' | 'THINKING_LEVEL_LOW' | 'THINKING_LEVEL_MEDIUM' | 'THINKING_LEVEL_HIGH' | 'THINKING_LEVEL_MINIMAL': ThinkingLevel is the thinking level that the agent will use. - THINKING_LEVEL_AUTO: Some models have a thinking budget. - THINKING_LEVEL_MINIMAL: As little reasoning as the model allows, for short latency-bound calls. Models without a minimal setting use their lowest one. - `tools` SpecTools[]: The tools of the AI request. - `description` string: The description of the tool. - `name` string, required: The name of the tool. - `schema` object: The schema of input to the tool. - `top_p` number, float: topN of the AI request. - `output` SpecOutput: Output message for the AI request. - `choices` OutputChoice[] - `finish_reason` 'FINISH_REASON_UNSPECIFIED' | 'FINISH_REASON_STOP' | 'FINISH_REASON_TOOLS_CALL' - `index` integer: The index of the choice. - `message` SpecMessage - `role` 'ROLE_UNSPECIFIED' | 'ROLE_SYSTEM' | 'ROLE_USER' | 'ROLE_ASSISTANT' | 'ROLE_TOOLS', required - `text` string - `tool_calls` SpecToolCall[]: The tool calls of the message. This is only present if the role is ROLE_TOOLS. This is the list of tools that the LLM needs to call. - `function` ToolCallToolCallFunction - … - `id` string, required: The id of the tool call. - `completion_usage` OutputCompletionUsage: Completion usage of the AI request. - `caching_tokens` integer: The number of caching tokens of the AI request. - `completion_tokens` integer: The number of completion tokens of the AI request. - `prompt_tokens` integer: The number ofprompt tokens of the AI request. - `reasoning_tokens` integer: The number of reasoning tokens of the AI request. - `total_tokens` integer: The total number of tokens of the AI request. - `id` string: The id of the AI request. - `serving_attribution` V1AIServingAttribution: AIServingAttribution records route and usage completeness for a fresh response. - `route` 'AI_SERVING_ROUTE_UNSPECIFIED' | 'AI_SERVING_ROUTE_AZURE_OPENAI' | 'AI_SERVING_ROUTE_AZURE_AI_INFERENCE' | 'AI_SERVING_ROUTE_OPENAI_DIRECT' | 'AI_SERVING_ROUTE_OPENAI_COMPATIBLE' | 'AI_SERVING_ROUTE_VERTEX_AI' | 'AI_SERVING_ROUTE_GEMINI_API' | 'AI_SERVING_ROUTE_ANTHROPIC_API' | 'AI_SERVING_ROUTE_GROQ_API' | 'AI_SERVING_ROUTE_FIREWORKS_API' | 'AI_SERVING_ROUTE_ENDOR_GATEWAY': AIServingRoute classifies the selected service entry point for an AI request. - AI_SERVING_ROUTE_UNSPECIFIED: No safe route classification is available. - AI_SERVING_ROUTE_AZURE_OPENAI: Azure OpenAI served the request. - AI_SERVING_ROUTE_AZURE_AI_INFERENCE: Azure AI Inference served the request. - AI_SERVING_ROUTE_OPENAI_DIRECT: The OpenAI API served the request directly. - AI_SERVING_ROUTE_OPENAI_COMPATIBLE: An OpenAI-compatible service served the request, with no known vendor claim. - AI_SERVING_ROUTE_VERTEX_AI: Vertex AI served the request. - AI_SERVING_ROUTE_GEMINI_API: The Gemini API served the request. - AI_SERVING_ROUTE_ANTHROPIC_API: The Anthropic API served the request. - AI_SERVING_ROUTE_GROQ_API: Groq served the request. - AI_SERVING_ROUTE_FIREWORKS_API: Fireworks served the request. - AI_SERVING_ROUTE_ENDOR_GATEWAY: The Endor gateway served the request. - `usage_complete` boolean: True only when all required raw usage fields were present and valid. False means incomplete. Unset means unknown. - `storage` SpecStorage - `enable_storage_persistence` boolean: Whether to store the AI request in the database. - `tenant_meta` object, required: The tenant metadata restricts access to a specific tenant. - `uuid` string: The uuid of the resource. ## Response `200` A successful response. - V1AIRequest: Implements qi request by interacting with the LLM API. - `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. - `spec` V1AIRequestSpec - `ai_feature` 'AI_FEATURE_UNSPECIFIED' | 'AI_FEATURE_SECURITY_REVIEW' | 'AI_FEATURE_AI_SAST' | 'AI_FEATURE_AIFP_EVALUATOR' | 'AI_FEATURE_LICENSE_EXTRACTION' | 'AI_FEATURE_MODEL_DISCOVERY' | 'AI_FEATURE_MODEL_METADATA_EXTRACTION' | 'AI_FEATURE_SKILL_SCORING' | 'AI_FEATURE_MCP_RISK_EVALUATION' | 'AI_FEATURE_AI_SAST_CONTEXT_SUMMARY' | 'AI_FEATURE_AGENT_POLICY_CMD_CLASSIFICATION' | 'AI_FEATURE_MALWARE_ANALYSIS': AIFeature identifies which AI feature is making the request. This is used for metrics, billing, and feature tracking. - AI_FEATURE_AI_SAST_CONTEXT_SUMMARY: AI SAST per-project context summarization that grounds segment prompts. - AI_FEATURE_AGENT_POLICY_CMD_CLASSIFICATION: Agent-governance adjudication of a command an agent hook policy flagged. - AI_FEATURE_MALWARE_ANALYSIS: Malware analysis of a published package version (ported sr-malware-detection LLM signals). - `byok` boolean: Deprecated: read credential_class instead. Still written, derived from it, so readers have one release to move. Indicates the request was served through customer-provided (bring your own key) provider credentials, which bill the customer's provider account and do not consume platform credits. - `credential_class` 'AI_CREDENTIAL_CLASS_UNSPECIFIED' | 'AI_CREDENTIAL_CLASS_PLATFORM' | 'AI_CREDENTIAL_CLASS_BYOK': AICredentialClass names the provider account an AI request billed against. It supersedes the byok boolean, which cannot name a third kind of account and cannot say which of a tenant's keys served a request. The value names carry a constraint. Lowercased and stripped of the AI_CREDENTIAL_CLASS_ prefix, each one must equal the credential-class label value the LLM metrics use, so a stored record and a metric series never name the same account differently. A rename breaks that pairing silently. - AI_CREDENTIAL_CLASS_UNSPECIFIED: No class was assigned, so the record predates credential classification. - AI_CREDENTIAL_CLASS_PLATFORM: Endor's own provider account served the request. - AI_CREDENTIAL_CLASS_BYOK: The tenant's own provider account served the request, reached through one of their AI provider keys. - `credential_ref` string: The uuid of the AI provider key that served the request, empty unless the credential class is BYOK. The key's endpoint is a secure field and stays redacted on every read, so this reference is the indirection to it: it identifies the customer account that billed the request without widening what is queryable. - `input` SpecInput, required: Input message for the AI request. - `max_output_tokens` integer: MaxOutputTokens is the maximum number of tokens that the agent will output. - `messages` SpecMessage[]: The messages of the AI request. - `role` 'ROLE_UNSPECIFIED' | 'ROLE_SYSTEM' | 'ROLE_USER' | 'ROLE_ASSISTANT' | 'ROLE_TOOLS', required - `text` string - `tool_calls` SpecToolCall[]: The tool calls of the message. This is only present if the role is ROLE_TOOLS. This is the list of tools that the LLM needs to call. - `function` ToolCallToolCallFunction - `arguments` object: The arguments of the tool. - `description` string: The description of the tool. - `name` string: The name of the tool. - `results` object: The results of the tool. - `id` string, required: The id of the tool call. - `model` string, required: The model which will be used to generate the response of the AI request. - `response_format` InputResponseFormat: The response format of the message. - `description` string: The description of the response format. - `json_schema` object: The JSON schema of the response format. - `name` string: The name of the response format. - `strict` boolean: Whether the response format is strict. - `temperature` number, float: temperature of the AI request. - `thinking_level` 'THINKING_LEVEL_UNSPECIFIED' | 'THINKING_LEVEL_AUTO' | 'THINKING_LEVEL_LOW' | 'THINKING_LEVEL_MEDIUM' | 'THINKING_LEVEL_HIGH' | 'THINKING_LEVEL_MINIMAL': ThinkingLevel is the thinking level that the agent will use. - THINKING_LEVEL_AUTO: Some models have a thinking budget. - THINKING_LEVEL_MINIMAL: As little reasoning as the model allows, for short latency-bound calls. Models without a minimal setting use their lowest one. - `tools` SpecTools[]: The tools of the AI request. - `description` string: The description of the tool. - `name` string, required: The name of the tool. - `schema` object: The schema of input to the tool. - `top_p` number, float: topN of the AI request. - `output` SpecOutput: Output message for the AI request. - `choices` OutputChoice[] - `finish_reason` 'FINISH_REASON_UNSPECIFIED' | 'FINISH_REASON_STOP' | 'FINISH_REASON_TOOLS_CALL' - `index` integer: The index of the choice. - `message` SpecMessage - `role` 'ROLE_UNSPECIFIED' | 'ROLE_SYSTEM' | 'ROLE_USER' | 'ROLE_ASSISTANT' | 'ROLE_TOOLS', required - `text` string - `tool_calls` SpecToolCall[]: The tool calls of the message. This is only present if the role is ROLE_TOOLS. This is the list of tools that the LLM needs to call. - `function` ToolCallToolCallFunction - … - `id` string, required: The id of the tool call. - `completion_usage` OutputCompletionUsage: Completion usage of the AI request. - `caching_tokens` integer: The number of caching tokens of the AI request. - `completion_tokens` integer: The number of completion tokens of the AI request. - `prompt_tokens` integer: The number ofprompt tokens of the AI request. - `reasoning_tokens` integer: The number of reasoning tokens of the AI request. - `total_tokens` integer: The total number of tokens of the AI request. - `id` string: The id of the AI request. - `serving_attribution` V1AIServingAttribution: AIServingAttribution records route and usage completeness for a fresh response. - `route` 'AI_SERVING_ROUTE_UNSPECIFIED' | 'AI_SERVING_ROUTE_AZURE_OPENAI' | 'AI_SERVING_ROUTE_AZURE_AI_INFERENCE' | 'AI_SERVING_ROUTE_OPENAI_DIRECT' | 'AI_SERVING_ROUTE_OPENAI_COMPATIBLE' | 'AI_SERVING_ROUTE_VERTEX_AI' | 'AI_SERVING_ROUTE_GEMINI_API' | 'AI_SERVING_ROUTE_ANTHROPIC_API' | 'AI_SERVING_ROUTE_GROQ_API' | 'AI_SERVING_ROUTE_FIREWORKS_API' | 'AI_SERVING_ROUTE_ENDOR_GATEWAY': AIServingRoute classifies the selected service entry point for an AI request. - AI_SERVING_ROUTE_UNSPECIFIED: No safe route classification is available. - AI_SERVING_ROUTE_AZURE_OPENAI: Azure OpenAI served the request. - AI_SERVING_ROUTE_AZURE_AI_INFERENCE: Azure AI Inference served the request. - AI_SERVING_ROUTE_OPENAI_DIRECT: The OpenAI API served the request directly. - AI_SERVING_ROUTE_OPENAI_COMPATIBLE: An OpenAI-compatible service served the request, with no known vendor claim. - AI_SERVING_ROUTE_VERTEX_AI: Vertex AI served the request. - AI_SERVING_ROUTE_GEMINI_API: The Gemini API served the request. - AI_SERVING_ROUTE_ANTHROPIC_API: The Anthropic API served the request. - AI_SERVING_ROUTE_GROQ_API: Groq served the request. - AI_SERVING_ROUTE_FIREWORKS_API: Fireworks served the request. - AI_SERVING_ROUTE_ENDOR_GATEWAY: The Endor gateway served the request. - `usage_complete` boolean: True only when all required raw usage fields were present and valid. False means incomplete. Unset means unknown. - `storage` SpecStorage - `enable_storage_persistence` boolean: Whether to store the AI request in the database. - `tenant_meta` V1TenantMeta, required: 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/ai-requests/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/4acd9fe15140?raw)