Home / Sample report

A sample report, start to finish

What you get back after a review: what was read, what was found, why it matters and what to change. Real output, with the names removed.

127findings

16distinct causes

53operations read

968fragments of text read

4checks it could not make

Coverage: complete

Coverage says how much of what you gave us was actually read. A report that read only part of the input says so here and marks itself partial.

Source	Role	Coverage	Read	Not read	Failed
`fulfilment-api.json`	API description	complete	1	0	0

By area

Each area has its own sub-score out of 100, built only from the findings in that area. There is no single overall score, on purpose: one number would hide which part of the documentation is hurting developers.

Area	Sub-score	Findings	Rules applied
Contract	34	116	13
Pagination	85	5	1
Onboarding	98	2	2
Data	99	1	1
Examples	99	1	2
Limits	99	1	1
Reliability	99	1	1
Documentation	not assessed	0	0
Errors	not assessed	0	0
Lifecycle	not assessed	0	0
Links	not assessed	0	0
Webhooks	not assessed	0	0
Workflow	not assessed	0	0

What it could not check

21 rules ran, 14 did not apply to this API, 2 are switched off by default, and 4 could not be assessed. A check that cannot be made is never counted as a pass and never takes points off.

CC-CONFLICT-01 The API description and a guide state different maximums for the same parameter. needs guide pages; none was supplied
LINK-01 In-scope documentation link returns 404/410, points to a missing anchor, or names a file that is not in the supplied documents. needs guide pages; none was supplied
ON-ENV-01 Code sample uses a placeholder that no text explains. needs guide pages; none was supplied
DOC-CODE-01 A JSON code sample is not valid JSON. needs guide pages; none was supplied

Findings, grouped by cause

Findings of one rule with the same problem at different places count as one cause, so 53 missing error responses read as one problem to fix, not 53.

HighCC-SCHEMA-01 Request or response declares a structured content type but no schema

no schema for application/json 2 places

Example: GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}: response declares application/json but no schema

Recommendation. Add a schema to each structured media type, or remove the media type if no body is exchanged.

Show all 2 places

GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}
GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames

MediumCC-ERR-01 Operation documents no error response

no error response documented 53 places

Example: GET /api/fulfilment/v1/configuration/warehouses/{warehouseId} documents no error responses

Recommendation. Document the error responses (4xx and 5xx or a default) with their bodies and when each occurs.

Show all 53 places

GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}
GET /api/fulfilment/v1/configuration/warehouses
POST /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}/transfer
POST /api/fulfilment/v1/configuration/docks/{dockId}/activation
DELETE /api/fulfilment/v1/configuration/warehouses/{warehouseId}
GET /api/fulfilment/v1/inventory/skus/{skuId}
GET /api/fulfilment/v1/configuration/geoshape
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm
PUT /api/fulfilment/v1/configuration/geoshape
PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId}
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}
GET /api/fulfilment/v1/inventory/reservations/{reservationId}
PUT /api/fulfilment/v1/configuration/holidays/{holidayId}
GET /api/fulfilment/v1/configuration/docks
POST /api/fulfilment/v1/configuration/freights/{carrierId}/values/update
POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/activation
POST /api/fulfilment/v1/shipping/calculate
DELETE /api/fulfilment/v1/configuration/geoshape/{polygonName}
GET /api/fulfilment/v1/configuration/geoshape/{polygonName}
POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/deactivation
POST /api/fulfilment/v1/shipping-policies
GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched
GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values
GET /api/fulfilment/v1/shipping-policies
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}/warehouses/{warehouseId}
GET /api/fulfilment/v1/configuration/carriers/{carrierId}/getdayofweekblocked
POST /api/fulfilment/v1/configuration/carriers/{carrierId}/adddayofweekblocked
GET /api/fulfilment/v1/inventory/reservations/{warehouseId}/{skuId}
DELETE /api/fulfilment/v1/shipping-policies/{id}
POST /api/fulfilment/v1/configuration/carriers/{carrierId}/removedayofweekblocked
POST /api/fulfilment/v1/configuration/docks
POST /api/fulfilment/v1/configuration/warehouses
GET /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}
GET /api/fulfilment/v1/configuration/holidays
DELETE /api/fulfilment/v1/configuration/holidays/{holidayId}
POST /api/fulfilment/v1/inventory/reservations
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/cancel
GET /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots
POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation
DELETE /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
GET /api/fulfilment/v1/shipping-policies/{id}
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/acknowledge
GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}
PUT /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}
GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
PUT /api/fulfilment/v1/shipping-policies/{id}
GET /api/fulfilment/v1/configuration/pickuppoints/_search
GET /api/fulfilment/v1/configuration/pickuppoints
PUT /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
GET /api/fulfilment/v1/configuration/holidays/{holidayId}
GET /api/fulfilment/v1/configuration/docks/{dockId}
DELETE /api/fulfilment/v1/configuration/docks/{dockId}
GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames

MediumCC-PARAM-01 Required parameter or required request property has no description

required parameter without description 42 places

Example: Required path parameter `warehouseId` has no description

Recommendation. Describe what the parameter means, its format and valid values.

Show all 42 places

GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}
DELETE /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
DELETE /api/fulfilment/v1/configuration/holidays/{holidayId}
GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
GET /api/fulfilment/v1/configuration/pickuppoints/_search
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}/warehouses/{warehouseId}
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}
GET /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}
POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/activation
DELETE /api/fulfilment/v1/configuration/warehouses/{warehouseId}
POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation
GET /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}
PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId}
POST /api/fulfilment/v1/configuration/carriers/{carrierId}/adddayofweekblocked
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/cancel
POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/deactivation
PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId}
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/acknowledge
GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched
GET /api/fulfilment/v1/inventory/skus/{skuId}
GET /api/fulfilment/v1/inventory/reservations/{reservationId}
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}/warehouses/{warehouseId}
GET /api/fulfilment/v1/configuration/geoshape/{polygonName}
GET /api/fulfilment/v1/configuration/holidays/{holidayId}
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm
GET /api/fulfilment/v1/configuration/pickuppoints/_search
GET /api/fulfilment/v1/configuration/carriers/{carrierId}/getdayofweekblocked
GET /api/fulfilment/v1/configuration/pickuppoints/_search
GET /api/fulfilment/v1/configuration/docks/{dockId}
GET /api/fulfilment/v1/configuration/geoshape
PUT /api/fulfilment/v1/configuration/holidays/{holidayId}
POST /api/fulfilment/v1/configuration/freights/{carrierId}/values/update
GET /api/fulfilment/v1/inventory/reservations/{warehouseId}/{skuId}
GET /api/fulfilment/v1/inventory/reservations/{warehouseId}/{skuId}
DELETE /api/fulfilment/v1/configuration/geoshape/{polygonName}
GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched
POST /api/fulfilment/v1/configuration/docks/{dockId}/activation
GET /api/fulfilment/v1/configuration/geoshape
GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}/warehouses/{warehouseId}
DELETE /api/fulfilment/v1/configuration/docks/{dockId}
POST /api/fulfilment/v1/configuration/carriers/{carrierId}/removedayofweekblocked

MediumPAG-01 List operation does not document how to page through results

no pagination 5 places

Example: GET /api/fulfilment/v1/configuration/warehouses returns a collection with no documented pagination

Recommendation. Document a pagination mechanism (cursor or page parameters and the field or header carrying the next position).

Show all 5 places

GET /api/fulfilment/v1/configuration/warehouses
GET /api/fulfilment/v1/configuration/docks
GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values
GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched
GET /api/fulfilment/v1/configuration/pickuppoints

MediumCC-CONSIST-01 The same property has incompatible types in different schemas

conflicting types for freight-values.absolutemoneycost 1 place

Example: Property `absoluteMoneyCost` has different types across variants of `freight-values`: number in `ListFreightValues`, string in `CreateUpdateFreightValuesRequest`

Recommendation. Use one type for a property name across schemas, or rename one of them to say it is a different thing.

MediumCC-PARAM-01 Required parameter or required request property has no description

required request property without description 1 place

Example: Required request property `cubicWeightSettings.minimunAcceptableVolumetricWeight` has no description

Recommendation. Describe what the property means, its format and valid values.

LowCC-DESC-02 Description is a placeholder, only repeats the name, or is too short to help

weak description: restates its name 9 places

Example: The description of POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm is weak (restates its name)

Recommendation. Say what it does, what it returns or accepts, and anything the name does not show.

Show all 9 places

POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm
POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/activation
PUT /api/fulfilment/v1/configuration/holidays/{holidayId}
POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/deactivation
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/acknowledge
POST /api/fulfilment/v1/inventory/reservations/{reservationId}/cancel
POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation
PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId}
POST /api/fulfilment/v1/configuration/docks/{dockId}/activation

LowCC-RESP-01 Response has no description

response without description 4 places

Example: Response has no description

Recommendation. Describe when this response is returned and what it contains.

Show all 4 places

PUT /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
GET /api/fulfilment/v1/inventory/skus/{skuId}
GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}
POST /api/fulfilment/v1/shipping/calculate

LowCC-DESC-02 Description is a placeholder, only repeats the name, or is too short to help

weak description: too short 2 places

Example: The description of parameter `postalCode` is weak (too short)

Recommendation. Say what it does, what it returns or accepts, and anything the name does not show.

Show all 2 places

GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values
GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values

LowAUTH-02 Security scheme has no description

security scheme without description 2 places

Example: Security scheme `appToken` has no description

Recommendation. Describe how to obtain credentials and how to send them.

Show all 2 places

LowNAME-01 Inconsistent casing of paths or query parameters, or verbs in some paths

verbs in some paths 1 place

Example: 1 of 40 paths put an action verb in the path while the rest do not

Recommendation. Name paths after resources and express the action with the HTTP method.

LowNAME-01 Inconsistent casing of paths or query parameters, or verbs in some paths

inconsistent casing: kebab-case,snake_case,camelcase 1 place

Example: paths mix kebab-case, snake_case, camelCase with no dominant convention

Recommendation. Choose one naming convention and apply it everywhere; keep old names only as documented deprecated aliases.

LowDATA-02 Date/time property has no format or timezone information

unformatted date/time properties 1 place

Example: 25 date/time-named string properties declare no format or timezone

Recommendation. Set `format: date-time` or `date`, or describe the format and timezone (for example ISO 8601 in UTC).

LowCC-EX-01 Operation with a body has no example request or response

no request or response example 1 place

Example: PUT /api/fulfilment/v1/configuration/geoshape has no example request or response

Recommendation. Add a realistic example for the request body and the success response.

LowRATE-01 API documents no rate limiting

no rate limit documentation 1 place

Example: No rate limiting is documented

Recommendation. Document the limits, a 429 response and the headers that report remaining quota and when to retry.

LowIDEM-01 Resource-creating POST has no idempotency key

no idempotency 1 place

Example: None of the 4 resource-creating POST operations documents an idempotency key

Recommendation. Accept an Idempotency-Key header on creating operations and document how long keys are remembered.

One finding in full

HighCC-SCHEMA-01 Request or response declares a structured content type but no schema

GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}: response declares application/json but no schema

Operation: GET /api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}
State: Not in the specification
Evidence: Not found: a schema for application/json. Looked at fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime…
Impact: Developers cannot know the fields, types or required properties, and generated clients fall back to untyped data.
Recommendation: Add a schema to each structured media type, or remove the media type if no body is exchanged.

Confidence 1.00 · fingerprint 3793ec222369

Every rule, and what happened to it

Rule	What it looks for	Result	Findings
`CC-REF-01`	Internal $ref that does not resolve	Not applicable	0
`CC-DESC-01`	Operation has neither summary nor description	Applied	0
`CC-PARAM-01`	Required parameter or required request property has no description	Applied	43
`CC-RESP-01`	Response has no description	Applied	4
`CC-ERR-01`	Operation documents no error response	Applied	53
`CC-EX-01`	Operation with a body has no example request or response	Applied	1
`CC-EX-02`	Request or success-response example does not validate against its own schema	Applied	0
`ERR-05`	Error response example does not validate against its own schema	Not applicable	0
`CC-CONFLICT-01`	The API description and a guide state different maximums for the same parameter	Could not be assessed	0
`CC-PATH-01`	Path placeholder has no path parameter definition	Applied	0
`CC-SCHEMA-01`	Request or response declares a structured content type but no schema	Applied	2
`CC-TYPE-01`	Path or query parameter has no type information	Applied	0
`CC-CONSIST-01`	The same property has incompatible types in different schemas	Applied	1
`RATE-02`	429 is documented without telling clients when to retry	Not applicable	0
`WH-01`	Webhook or callback has no payload schema	Not applicable	0
`WH-02`	Webhook signature verification is not described	Not applicable	0
`WH-03`	Webhook delivery retries and acknowledgement are not described	Not applicable	0
`AUTH-03`	Where credentials come from is not described	Not applicable	0
`IDEM-02`	Idempotency key lifetime and reuse are not described	Not applicable	0
`ERR-04`	Which failures are worth retrying is not described	Not applicable	0
`WF-04`	202 Accepted response does not say how to learn the outcome	Not applicable	0
`DATA-02`	Date/time property has no format or timezone information	Applied	1
`DATA-03`	Date/time example has no timezone although the contract says it has one	Not applicable	0
`CC-ENV-01`	Server description and address point to different environments	Applied	0
`AUTH-04`	OAuth2 scopes are not described or not tied to operations	Not applicable	0
`AUTH-01`	No usable authentication described	Applied	0
`AUTH-02`	Security scheme has no description	Applied	2
`CC-SEC-01`	Operation requires a security scheme that is not defined	Applied	0
`NAME-01`	Inconsistent casing of paths or query parameters, or verbs in some paths	Applied	2
`PAG-01`	List operation does not document how to page through results	Applied	5
`PAG-02`	List operations use different pagination styles	Switched off	0
`RATE-01`	API documents no rate limiting	Applied	1
`ERR-02`	Error responses lack a shared, machine-readable shape	Not applicable	0
`IDEM-01`	Resource-creating POST has no idempotency key	Applied	1
`CC-DEP-01`	Deprecated operation does not say what to use instead	Not applicable	0
`CC-DESC-02`	Description is a placeholder, only repeats the name, or is too short to help	Applied	11
`CC-DESC-03`	Description uses vague wording (etc., various, as needed)	Switched off	0
`CC-DESC-04`	Several operations share the same description	Applied	0
`LINK-01`	In-scope documentation link returns 404/410, points to a missing anchor, or names a file that is not in the supplied documents	Could not be assessed	0
`ON-ENV-01`	Code sample uses a placeholder that no text explains	Could not be assessed	0
`DOC-CODE-01`	A JSON code sample is not valid JSON	Could not be assessed	0

Take it with you

The same review as files. The report is sealed: its fingerprint is 22aca6e881d84c15, and changing any finding changes it.

report.md, the full report as readable text
report.json, the sealed report as data
report.sarif, for code-scanning tools that read SARIF
manifest.json, the evidence manifest: which rules ran, at which version, over which input

Get a free first review See the diff view