{"id":50104566,"url":"https://github.com/jentic/jentic-api-scorecard","last_synced_at":"2026-05-27T13:00:58.362Z","repository":{"id":359359498,"uuid":"1245446591","full_name":"jentic/jentic-api-scorecard","owner":"jentic","description":"Jentic API Scorecard","archived":false,"fork":false,"pushed_at":"2026-05-26T12:36:32.000Z","size":2108,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T12:36:51.122Z","etag":null,"topics":["api","openapi","quality","score","scorecard","scoring"],"latest_commit_sha":null,"homepage":"https://jentic.com/scorecard","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jentic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T08:22:43.000Z","updated_at":"2026-05-26T12:36:34.000Z","dependencies_parsed_at":"2026-05-25T11:01:37.427Z","dependency_job_id":null,"html_url":"https://github.com/jentic/jentic-api-scorecard","commit_stats":null,"previous_names":["jentic/jentic-api-scorecard"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/jentic/jentic-api-scorecard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jentic%2Fjentic-api-scorecard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jentic%2Fjentic-api-scorecard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jentic%2Fjentic-api-scorecard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jentic%2Fjentic-api-scorecard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jentic","download_url":"https://codeload.github.com/jentic/jentic-api-scorecard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jentic%2Fjentic-api-scorecard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33566873,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","openapi","quality","score","scorecard","scoring"],"created_at":"2026-05-23T09:41:04.342Z","updated_at":"2026-05-27T13:00:58.300Z","avatar_url":"https://github.com/jentic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jentic API Scorecard\n\n![Jentic API Scorecard preview](assets/scorecard-preview.jpg)\n\nA spec that passes OpenAPI validation isn't necessarily one an AI agent can use. Grammar is one\nthing; semantic clarity, safety, and discoverability are another. The Jentic API Scorecard measures\nwhere your spec stands on the second question — scoring it against the\n[Jentic API AI Readiness Framework (JAIRF)](https://github.com/jentic/api-ai-readiness-framework)\nacross six dimensions and returning a single grade.\n\nThe project ships in two pieces: the public Docker image `ghcr.io/jentic/jentic-api-scorecard`,\nand an `@jentic/api-scorecard-cli` npm CLI that orchestrates the image. Both are tracked in this\nmonorepo (`packages/cli/` for the CLI, `docker/` for the image). Per-phase progress lives in\n[`specs/roadmap.md`](specs/roadmap.md).\n\n## What it scores\n\nEach spec is evaluated across six lenses — small, targeted improvements in any of them tend to\nproduce outsized gains for both human developers and AI agents:\n\n- **Foundational Compliance (FC)** — structural validity and conformance to OpenAPI itself.\n- **Developer Experience \u0026 Jentic Compatibility (DXJ)** — documentation quality and how well the\n  spec plays with downstream tooling.\n- **AI-Readiness \u0026 Agent Experience (ARAX)** — semantic clarity and the context an LLM needs to\n  reason about each operation.\n- **Agent Usability (AU)** — predictable, safe multi-step orchestration.\n- **Security (SEC)** — declared auth schemes and trust boundaries.\n- **AI Discoverability (AID)** — how easily an AI system can find and parse the spec.\n\n## What it does\n\nPass an OpenAPI spec — by URL or by piping bundled JSON to the container — and the scorer evaluates\nit across the six dimensions above and emits the result as JSON. Today the published Docker image\nis JSON-only; piping its output to `jq` is the way to read a score:\n\n```bash\ndocker run --rm ghcr.io/jentic/jentic-api-scorecard:unstable \\\n  score --url https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swagger-api/petstore/1.0.27/openapi.json \\\n  | jq '.summary | {score, level, grade, dimensions: [.dimensions[] | {kind, name, score, grade}]}'\n```\n\nExample output:\n\n```json\n{\n  \"score\": 68.62,\n  \"level\": \"ai-aware\",\n  \"grade\": \"B+\",\n  \"dimensions\": [\n    { \"kind\": \"FC\",   \"name\": \"Foundational Compliance\",                     \"score\": 99.51,  \"grade\": \"A+\" },\n    { \"kind\": \"DXJ\",  \"name\": \"Developer Experience \u0026 Jentic Compatibility\", \"score\": 68.89,  \"grade\": \"B+\" },\n    { \"kind\": \"ARAX\", \"name\": \"AI-Readiness \u0026 Agent Experience\",             \"score\": 54.62,  \"grade\": \"C\"  },\n    { \"kind\": \"AU\",   \"name\": \"Agent Usability\",                             \"score\": 93.70,  \"grade\": \"A+\" },\n    { \"kind\": \"SEC\",  \"name\": \"Security\",                                    \"score\": 42.50,  \"grade\": \"D-\" },\n    { \"kind\": \"AID\",  \"name\": \"AI Discoverability\",                          \"score\": 100.00, \"grade\": \"A+\" }\n  ]\n}\n```\n\n## How it works\n\nScoring runs locally inside the container in two phases. **Analysis** runs a battery of validators\nand structural checks against the spec — and, with `--with-llm`, LLM-backed signals on top — to\nproduce a set of diagnostics and observations. **Scoring** maps those into ~35 signals across the six\nJAIRF dimensions, aggregates them into per-dimension scores, and rolls those up into a single weighted\nscore and grade. Anonymous scoring is restricted to specs in\n[jentic-public-apis](https://github.com/jentic/jentic-public-apis); other inputs require\n`JENTIC_API_KEY=mvp-preview` (a documented public placeholder for the MVP preview, not a secret).\n\n## Requirements\n\n- **Docker** installed and running. See [Docker installation](https://docs.docker.com/get-docker/).\n- Network access to `ghcr.io` (to pull the image) and to whatever URL hosts the spec you're scoring\n  (the engine fetches it from inside the container).\n\n## Quick start\n\n### Score an allowlisted public spec\n\nNo key required (swap in any other path under\n[jentic-public-apis/apis/openapi/](https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi)):\n\n```bash\ndocker run --rm ghcr.io/jentic/jentic-api-scorecard:unstable \\\n  score --url https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swagger-api/petstore/1.0.27/openapi.json \\\n  | jq '.summary | {score, level, grade, dimensions: [.dimensions[] | {kind, name, score, grade}]}'\n```\n\n### Score any other URL — set the MVP preview key\n\n```bash\ndocker run --rm -e JENTIC_API_KEY=mvp-preview ghcr.io/jentic/jentic-api-scorecard:unstable \\\n  score --url https://petstore3.swagger.io/api/v3/openapi.json \\\n  | jq '.summary | {score, level, grade, dimensions: [.dimensions[] | {kind, name, score, grade}]}'\n```\n\n### Pipe a local spec via stdin\n\n```bash\ncat openapi.json | docker run -i --rm -e JENTIC_API_KEY=mvp-preview ghcr.io/jentic/jentic-api-scorecard:unstable \\\n  score \\\n  | jq '.summary | {score, level, grade, dimensions: [.dimensions[] | {kind, name, score, grade}]}'\n```\n\n## LLM-backed analysis\n\nAdd `--with-llm` to enable LLM-backed signal analysis. Forward at least one supported provider's\nkeys to the container with `-e \u003cNAME\u003e` — no `=value`; Docker copies the value from your shell at\nrun time, so the key never lands in your shell history:\n\n| Provider    | Forward with                                                  |\n| ----------- | ------------------------------------------------------------- |\n| OpenAI      | `-e OPENAI_API_KEY`                                           |\n| Anthropic   | `-e ANTHROPIC_API_KEY`                                        |\n| Gemini      | `-e GEMINI_API_KEY`                                           |\n| AWS Bedrock | `-e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION` |\n\nFor AWS Bedrock with temporary credentials (e.g. `aws sts assume-role`, AWS SSO), also forward\n`-e AWS_SESSION_TOKEN`.\n\nBy default the engine routes LLM calls to Bedrock-hosted Claude. To use a non-Bedrock provider you\nmust point the engine at it explicitly: set `LLM_PROVIDER`, `LLM_LIGHT_PROVIDER`, and pick an\n`LLM_LIGHT_MODEL` for that provider. Without `LLM_LIGHT_MODEL` the engine falls back to a Bedrock\nmodel ID and the run will fail for non-Bedrock providers.\n\nExample (OpenAI, allowlisted public spec — no `JENTIC_API_KEY` needed):\n\n```bash\ndocker run --rm \\\n  -e OPENAI_API_KEY \\\n  -e LLM_PROVIDER=openai \\\n  -e LLM_LIGHT_PROVIDER=openai \\\n  -e LLM_LIGHT_MODEL=gpt-4o \\\n  ghcr.io/jentic/jentic-api-scorecard:unstable \\\n  score --with-llm \\\n  --url https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swagger-api/petstore/1.0.27/openapi.json \\\n  | jq '.summary | {score, level, grade, dimensions: [.dimensions[] | {kind, name, score, grade}]}'\n```\n\n\n## Status\n\nThe GHCR image is the production-supported entry point — direct `docker run` is fully documented,\nand the only published tag is `:unstable`. `:unstable` is rebuilt on every push to `main`. Docker\ncaches by tag name, so subsequent runs reuse your local copy — pass `--pull=always` when you want\nthe latest build.\n\n```bash\ndocker run --pull=always --rm ghcr.io/jentic/jentic-api-scorecard:unstable \\\n  score --url https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swagger-api/petstore/1.0.27/openapi.json \\\n  | jq '.summary | {score, level, grade, dimensions: [.dimensions[] | {kind, name, score, grade}]}'\n```\n\nThe `@jentic/api-scorecard-cli` npm CLI (in `packages/cli/`) wraps the image with a friendlier\ninvocation and is built end-to-end against the published GHCR image. It currently streams the\nengine's verbatim JSON to stdout — pretty / Markdown rendering, `--detail` / `--format` / `-o` /\n`--quiet` / `--verbose`, and the `npx @jentic/api-scorecard-cli` distribution itself land in later\nphases.\n\n## License\n\nJentic API Scorecard is licensed under the [Apache 2.0](LICENSE) license. Jentic API Scorecard comes\nwith an explicit [NOTICE](NOTICE) file containing additional legal notices and information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjentic%2Fjentic-api-scorecard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjentic%2Fjentic-api-scorecard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjentic%2Fjentic-api-scorecard/lists"}