API Contract Drift Detection Prompt

Use this prompt when you need to programmatically compare the actual behavior of a live API against its documented specification (OpenAPI, protobuf, or manual docs). The prompt is designed for API governance teams, platform engineers, and QA leads who must catch undocumented parameters, type mismatches, missing endpoints, and stale error code references before they break downstream consumers. This is not a prompt for generating documentation from scratch. It assumes you already have a spec and a live API to test against. The prompt works best as part of a CI/CD pipeline where contract tests run on every deployment.

The ideal user has access to both a machine-readable API specification and a running instance of the API. Required context includes the full spec file, a representative set of live request/response pairs, and any known environment-specific behavior (sandbox vs. production, region-specific endpoints, feature flags). The prompt expects structured inputs: a spec block, a set of observed responses, and a clear output schema for the drift report. Without these, the model will hallucinate discrepancies or miss real drift. Do not use this prompt for one-off manual audits where you lack automated access to live API responses—the value comes from repeatable, evidence-backed comparison.

Avoid this prompt when you are generating documentation from scratch, reviewing documentation style, or evaluating developer experience. Those tasks require different prompts focused on authoring, style enforcement, or DX scoring. Also avoid this prompt when the API spec itself is the source of truth under active development and the live API is not yet stable—drift detection against a moving target produces noise, not signal. For high-risk APIs (payments, healthcare, auth), always route the drift report through human review before blocking a deployment. The prompt flags discrepancies; it does not decide which side—spec or implementation—is correct.

This is the core prompt for the API Contract Drift Detection workflow. It instructs the model to act as an API governance auditor, comparing a provided OpenAPI specification against a log of actual request/response traffic. The prompt is designed to produce a structured drift report that your application can parse, store, and use to trigger alerts or block deployments. Replace every square-bracket placeholder with your own data before execution. The prompt assumes you have already collected a representative sample of live traffic and have a valid OpenAPI spec file.

textCopy
You are an API governance auditor. Your task is to compare a documented API contract against observed live API behavior and produce a structured drift report.

## INPUTS
- OpenAPI Specification: [OPENAPI_SPEC]
- Live Traffic Log: [TRAFFIC_LOG]
- Traffic Log Format Description: [LOG_FORMAT_DESCRIPTION]

## OUTPUT_SCHEMA
Return a single JSON object conforming to this schema:
{
  "summary": "string (one-sentence summary of overall drift severity)",
  "drift_entries": [
    {
      "severity": "ERROR | WARNING | INFO",
      "category": "MISSING_ENDPOINT | EXTRA_ENDPOINT | TYPE_MISMATCH | MISSING_PARAMETER | EXTRA_PARAMETER | UNDOCUMENTED_ERROR | STATUS_CODE_MISMATCH | SCHEMA_DRIFT",
      "location": "string (endpoint path and method, e.g., GET /users/{id})",
      "documented_behavior": "string (what the spec says)",
      "observed_behavior": "string (what the traffic log shows)",
      "evidence": "string (specific log entry ID, timestamp, or request/response snippet)",
      "recommendation": "string (action to resolve the drift)"
    }
  ],
  "statistics": {
    "total_endpoints_documented": "integer",
    "total_endpoints_observed": "integer",
    "drift_count_by_severity": {
      "ERROR": "integer",
      "WARNING": "integer",
      "INFO": "integer"
    }
  }
}

## CONSTRAINTS
- Only report drift you can confirm with specific evidence from the traffic log.
- Do not flag optional parameters as missing unless they are marked as required in the spec.
- Treat any 5xx error not documented in the spec as UNDOCUMENTED_ERROR with WARNING severity.
- Treat any endpoint in the traffic log not present in the spec as EXTRA_ENDPOINT with ERROR severity.
- Treat any endpoint in the spec with zero observed traffic as INFO severity, noting it may be unused.
- If the traffic log contains authentication headers or tokens, do not include them in the evidence field.
- If you cannot determine drift with high confidence, omit the entry rather than guessing.

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[HIGH_RISK: This report may be used to block production deployments. Flag all uncertainties explicitly.]

To adapt this prompt, start by replacing [OPENAPI_SPEC] with the full text of your OpenAPI specification. For [TRAFFIC_LOG], provide a structured log of recent API calls—ideally in JSON Lines format with fields for method, path, request headers, request body, response status, and response body. Describe the log's schema in [LOG_FORMAT_DESCRIPTION] so the model can parse it correctly. The [EXAMPLES] placeholder should contain 2-3 few-shot examples of correct drift entries to calibrate the model's output style and severity judgment. The [RISK_LEVEL] placeholder should be set to HIGH_RISK if this report gates deployments, or MEDIUM_RISK if it is advisory only. After generation, always validate the output against the JSON schema before ingesting it into your drift dashboard or CI pipeline.

This prompt is designed to be a deterministic step in a software pipeline, not a conversational assistant. The implementation harness should treat it as a function: accept a structured specification and a set of live API observations, return a structured drift report. The model call itself is the central transformation, but the surrounding harness is responsible for input assembly, output validation, retry logic, and artifact storage. The goal is to produce a machine-readable drift report that can block a deployment, open a ticket, or update a compliance dashboard without a human reading raw model output.

Input Assembly: The harness must gather two primary inputs: the authoritative contract (an OpenAPI spec, a protobuf schema, or a structured JSON contract) and the live API evidence (a HAR file, a Postman collection run, or structured logs from a contract testing tool like Dredd or Schemathesis). These inputs should be serialized into the [CONTRACT_SPEC] and [LIVE_API_TRACES] placeholders. The [CONTRACT_SPEC] should be a minified JSON string to save tokens, while [LIVE_API_TRACES] should be a normalized array of request/response pairs with timestamps and status codes. Model Choice: Use a model with strong JSON mode and long-context capabilities (e.g., gpt-4o, claude-3-5-sonnet). Set response_format to json_object and provide the exact output schema in the [OUTPUT_SCHEMA] placeholder. Validation and Retries: After the model returns, validate the JSON against the expected schema immediately. If validation fails, retry up to two times with the validation error message appended to the prompt as additional context. If the model hallucinates endpoints not present in either input, flag the entire run for human review. Logging and Artifacts: Store the full prompt, the raw model response, the validated drift report, and the validation status in an immutable artifact store (S3, GCS, or a build artifact system). This audit trail is critical for governance reviews.

CI/CD Integration Pattern: Run this prompt as a gated step in your API deployment pipeline. After deploying to a staging environment, execute a contract test suite against the live deployment. Feed the contract spec and the test results into this prompt. If the drift report contains any severity: 'breaking' findings, fail the pipeline. For severity: 'warning' findings, create a non-blocking ticket in your issue tracker. Human Review Triggers: Always require human review when the model reports undocumented endpoints (potential shadow APIs), missing authentication requirements, or type mismatches in error response schemas. These are high-signal findings that often indicate security or reliability risks. What to Avoid: Do not use this prompt as a real-time monitor on production traffic; the latency and cost are better suited for pre-release gates. Do not skip the output validation step—models can and will hallucinate parameter names or status codes. Finally, do not treat the drift report as a source of truth for automatic spec updates; it is a detection tool, not an authoring tool. The next step after a drift finding should always be a human decision: update the spec, fix the code, or document the intentional deviation.