{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/commands/score","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/commands/score","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{"sidebar":"sidebar-docs-cli.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"score","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"score","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["score"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["score"]}," command analyzes an OpenAPI description and produces a composite ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Agent Readiness"]}," score (0–100) that measures how easy the API is to integrate and how usable it is by AI agents and LLM-based tooling. Higher is better."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to the top-level score, the command reports normalized subscores, raw metrics for every operation, and a list of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["hotspot operations"]}," — the endpoints most likely to cause integration friction — along with human-readable explanations."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["score"]}," command is considered an experimental feature. This means it's still a work in progress and may go through major changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["score"]}," command supports OpenAPI 3.x descriptions only."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"metrics","__idx":2},"children":["Metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following raw metrics are collected per operation and aggregated across the document:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Metric"},"children":["Metric"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parameter count"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total parameters (path, query, header, cookie) per operation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required parameter count"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How many of those parameters are required."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request body presence"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the operation defines a request body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top-level writable field count"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of non-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readOnly"]}," top-level properties in request schemas."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Max request/response schema depth"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deepest nesting level in request and response schemas."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Polymorphism count"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allOf"]}," usages. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyOf"]}," is penalized more heavily because it allows ambiguous combinations of schemas, making it harder for consumers and AI agents to determine the correct shape."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Property count"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total schema properties across request and response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Description coverage"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fraction of operations, parameters, and schema properties that have descriptions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ambiguous identifier count"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parameters with generic names (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},") and no description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Constraint coverage"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Count of constraining keywords (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["format"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pattern"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimum"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maximum"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minLength"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxLength"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discriminator"]},", etc.)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request/response example coverage"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether request and response media types include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Structured error response coverage"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How many 4xx/5xx responses include a content schema or meaningful description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Security scheme coverage"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether operations reference documented security schemes with descriptions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cross-operation dependency depth"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inferred from shared ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," usage across operations. Operations that share many schemas form a dependency graph; deeper graphs indicate tightly coupled multi-step interactions."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"subscores","__idx":3},"children":["Subscores"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following subscores are normalized to 0–1 and combined into the composite Agent Readiness score:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameterSimplicity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schemaSimplicity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documentationQuality"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["constraintClarity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exampleCoverage"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorClarity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dependencyClarity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifierClarity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["polymorphismClarity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discoverability"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discoverability"]}," subscore reflects the total number of operations in the API. Larger APIs (approaching 1,000+ operations) receive a lower discoverability score because finding the right endpoint becomes harder for both humans and AI agents."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hotspots","__idx":4},"children":["Hotspots"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The command identifies the operations with the lowest scores and provides reasons such as:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"High parameter count (N)\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Deep schema nesting (depth M)\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Polymorphism (anyOf) without discriminator\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Missing request and response examples\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"No structured error responses (4xx/5xx)\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["\"Missing operation description\""]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":5},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly score <api>\nredocly score <api> [--format=<option>]\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":6},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["api"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Path to the API description filename or alias that you want to score. Refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#specify-api"},"children":["the API section"]}," for more details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify path to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/configuration"},"children":["configuration file"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Format for the output.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stylish"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stylish"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--operation-details"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Print a per-operation metrics table sorted by property count."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--debug-operation-id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Print a detailed schema breakdown for a specific operation (by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["METHOD /path"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--help"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show help."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--lint-config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for the configuration file. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show version number."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":7},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specify-api","__idx":8},"children":["Specify API"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"pass-an-api-directly","__idx":9},"children":["Pass an API directly"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly score openapi/openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specify-output-format","__idx":10},"children":["Specify output format"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"stylish-output-default","__idx":11},"children":["Stylish output (default)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default output format shows a human-readable summary in your terminal:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"  Scores\n\n  Agent Readiness:  68.3/100\n\n  Subscores\n\n  Parameter Simplicity     [████████████████░░░░] 80%\n  Schema Simplicity        [██████████████░░░░░░] 70%\n  Documentation Quality    [████████████░░░░░░░░] 60%\n  Constraint Clarity       [██████████░░░░░░░░░░] 50%\n  Example Coverage         [████████████████████] 100%\n  Error Clarity            [████████████████░░░░] 80%\n  Dependency Clarity       [██████████████████░░] 90%\n  Identifier Clarity       [████████████████████] 100%\n  Polymorphism Clarity     [████████████████████] 100%\n  Discoverability          [████████████████████] 100%\n\n  Top 3 Hotspot Operations\n\n  POST /orders (createOrder)\n    Agent Readiness: 38.7\n    - High parameter count (12)\n    - Deep schema nesting (depth 6)\n    - Missing request and response examples\n\n  PUT /orders/{id} (updateOrder)\n    Agent Readiness: 44.0\n    - Polymorphism (anyOf) without discriminator (3 anyOf)\n    - No structured error responses (4xx/5xx)\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"json-output","__idx":12},"children":["JSON output"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--format=json"]}," for machine-readable output:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly score openapi.yaml --format=json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JSON output includes the full data: top-level scores, subscores, per-operation raw metrics, per-operation scores, dependency depths, and hotspot details with reasoning."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JSON format is suitable for CI pipelines, quality gates, or feeding results into dashboards."]}]},"headings":[{"value":"score","id":"score","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"Metrics","id":"metrics","depth":3},{"value":"Subscores","id":"subscores","depth":3},{"value":"Hotspots","id":"hotspots","depth":3},{"value":"Usage","id":"usage","depth":2},{"value":"Options","id":"options","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Specify API","id":"specify-api","depth":3},{"value":"Pass an API directly","id":"pass-an-api-directly","depth":4},{"value":"Specify output format","id":"specify-output-format","depth":3},{"value":"Stylish output (default)","id":"stylish-output-default","depth":4},{"value":"JSON output","id":"json-output","depth":4}],"frontmatter":{"seo":{"title":"score"}},"lastModified":"2026-04-19T14:14:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/commands/score","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}