API Namespace Routing Prompt

This prompt is for API platform teams building AI-assisted developer support, internal developer portals, or automated ticket routing systems. Its job is to take an unstructured developer question and map it to the correct API namespace, surface area, and version before any downstream tool, agent, or responder is invoked. Use this when a single platform exposes multiple APIs, SDKs, or versioned endpoints and wrong routing would surface incorrect documentation, deprecation warnings, or irrelevant code samples. The prompt assumes you maintain a current API taxonomy that includes namespaces, surface areas, and active versions.

Do not use this for general technical support classification that does not require version-specific routing. Do not use this for routing non-technical billing or account queries. The prompt is designed for inputs that contain explicit or implicit API surface references—such as endpoint paths, SDK method names, version strings, or error messages tied to specific API components. If your input lacks these signals, a broader domain classification prompt should precede this routing step. The prompt also assumes that your taxonomy is authoritative and versioned; stale taxonomies will produce confident but incorrect routing decisions that are hard to detect without explicit eval gates.

Before deploying, ensure you have a machine-readable taxonomy of your API surface area that includes namespace, surface name, active versions, and deprecation status. Wire the taxonomy into the prompt's [API_TAXONOMY] placeholder and version it alongside the prompt. If your platform has overlapping surface areas—such as a REST endpoint and an SDK method that serve the same capability—add explicit disambiguation rules to the taxonomy or implement a post-routing conflict resolution step. Start by running the prompt against a golden set of 50–100 labeled developer questions that span version-specific, cross-surface, and ambiguous cases to establish baseline accuracy before production use.

This prompt template is designed to be injected into your routing middleware. It takes a developer's technical question or request and maps it to a specific API namespace, version, and surface area from your defined taxonomy. The template uses square-bracket placeholders that you must replace with your organization's specific API taxonomy, versioning policy, and few-shot examples before deployment. The goal is deterministic, auditable routing that prevents misdirected requests from reaching the wrong engineering team or triggering incorrect tool dispatches.

textCopy
You are an API namespace router for [ORGANIZATION_NAME]'s developer platform. Your job is to analyze a developer's technical question or request and map it to the correct API namespace, version, and surface area.

## API Taxonomy
[API_TAXONOMY]

## Version Policy
[VERSION_POLICY]

## Routing Rules
- If the input mentions a specific API version, route to that version unless it is deprecated.
- If no version is specified, default to the latest stable version: [DEFAULT_VERSION].
- If the input spans multiple namespaces, select the primary namespace based on the core action or resource mentioned.
- If the input does not match any namespace, return `namespace: "out_of_scope"`.
- If the input is ambiguous between two namespaces, return both as candidates with a `confidence` score below 0.8 and request clarification.

## Few-Shot Examples
[FEW_SHOT_EXAMPLES]

## Input
Developer query: [INPUT]

## Output Schema
Return ONLY valid JSON matching this schema:
{
  "namespace": "string",
  "version": "string",
  "surface": "string",
  "confidence": 0.0,
  "candidates": [{"namespace": "string", "confidence": 0.0}],
  "reasoning": "string",
  "requires_clarification": false
}

## Constraints
[CONSTRAINTS]

To adapt this template, start by defining your [API_TAXONOMY] as a structured list of namespaces, surfaces, and the resources or actions each covers. Your [VERSION_POLICY] should specify which versions are stable, deprecated, or in preview, along with the default routing target. Populate [FEW_SHOT_EXAMPLES] with at least five real-world queries that exercise boundary cases—such as ambiguous namespace overlap, deprecated version references, and out-of-scope requests. The [CONSTRAINTS] placeholder is where you add organization-specific rules, such as "never route billing-related queries to the Payments API namespace" or "escalate any query mentioning admin or delete to human review." Before shipping, validate that the output JSON parses correctly and that the confidence field correlates with actual routing accuracy using a labeled test set of at least 50 queries.

The API Namespace Routing Prompt is designed to be called synchronously at the ingress layer of a developer support or API gateway platform. In a typical implementation, the raw user query is intercepted before it reaches any downstream tool, agent, or knowledge base. The prompt receives the query along with a curated list of available API namespaces, their descriptions, and their current version identifiers. The model's job is to return a structured classification object containing the selected namespace, a confidence score, and a brief rationale. This classification decision then determines which API reference docs, SDK examples, rate limits, and deprecation notices are injected into the subsequent retrieval or response-generation step.

Wire the prompt into your application using a thin orchestration layer that handles input assembly, model invocation, output validation, and fallback routing. Before calling the model, construct the [NAMESPACE_CATALOG] by pulling active API namespaces and their version strings from your service registry or API gateway metadata endpoint. This catalog must be current—stale namespace data is the most common cause of misrouting. After receiving the model's JSON response, validate it against a strict schema: namespace must match an entry in the provided catalog, confidence must be a float between 0.0 and 1.0, and rationale must be a non-empty string. If validation fails, retry once with the same input and a stronger constraint instruction appended to the prompt. If the retry also fails or returns confidence below your configured threshold (we recommend 0.7 as a starting point), route the query to a human review queue or a general-purpose fallback model. Log every classification decision—including the input query, selected namespace, confidence, rationale, and whether the result was auto-routed or escalated—so you can measure namespace drift, catalog gaps, and model accuracy over time.

For production deployment, use a fast, cost-effective model for this classification step. The task is a constrained selection problem, not a generation problem, so a smaller model with strong instruction-following and JSON output capabilities is usually sufficient. If you observe frequent misclassification between closely related namespaces (e.g., /v1/payments vs. /v2/payments), add disambiguation examples to the [EXAMPLES] placeholder that illustrate the distinguishing signals. Do not use this prompt for queries that are clearly out-of-scope (e.g., billing questions, account management, general platform status). Those should be caught by an upstream intent classifier before this prompt is invoked. The API Namespace Routing Prompt assumes the input is already known to be a technical API question; it is not a general triage prompt.