---
title: "Diagnostics"
description: "Deterministic, source-grounded API authorship findings for every immutable Definition Revision."
url: https://typeship.dev/docs/projects/diagnostics
markdown: https://typeship.dev/docs/projects/diagnostics.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# Diagnostics

Deterministic, source-grounded API authorship findings for every immutable Definition Revision.

**Diagnostics** help an API author improve the contract before poor names, ambiguous behavior, unsafe operations, or invalid schemas become permanent public interfaces.

Typeship analyzes the complete Definition with deterministic rules. It does not use a hosted model to invent descriptions, examples, API behavior, or opaque scores. Each Diagnostic has a stable semantic rule ID, severity, category, affected surfaces, exact source coordinates, evidence, and a grounded authoring brief.

Findings are grouped by rule rather than exploding one repeated issue into dozens of cards. OpenAPI and GraphQL use native coordinates and source-edit guidance. In a multi-document Definition, every location names the actual source document in addition to its resolved pointer.

## Remediation

When an exact OpenAPI edit can be proved from the contract, Typeship offers a reviewable patch. Repository sources can open a source pull request that edits the affected source documents; URL sources can keep the correction as a Definition overlay. Changes that require product intent remain source-edit guidance and explicitly tell an agent when to ask the API owner.

GraphQL remediation stays source-native. Typeship will not round-trip SDL through a lossy formatter or pretend OpenAPI patches apply to GraphQL.

## Policy and GitHub

The default policy blocks only new correctness errors. Teams can change the threshold, evaluate the complete current Definition instead of only new findings, or record reasoned rule/location exceptions.

Diagnostics are folded into `Typeship – API change review` on source pull requests. Typeship does not create a redundant status. The comment separates compatibility from Diagnostics so reviewers can distinguish an intentional breaking change from an invalid or underspecified contract.

Free projects get Diagnostics across the complete Definition even though each generated Target contains only the first 25 operations.

> **For AI agents:** Use 
> 
> `GET /projects/{project_id}/diagnostics`
> 
>  to read the latest immutable report and 
> 
> `POST /projects/{project_id}/diagnostics/remediations`
> 
>  with 
> 
> `diagnostic_ids`
> 
>  to apply only exact fixes. Preserve rule IDs and source coordinates in automation.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)