SEO API for Developers: Build a Safe Live CLI Adapter

By William Zhu · Cofounder, InfiniSynapse · Published: 2026-09-09 · Last updated: 2026-09-14 · Last verified: 2026-09-14 · Reviewed by the InfiniSynapse Data Team.

Reviewed by: InfiniSynapse Data Team · method review 2026-09-14. Registry GET for infinitegrowth plus six first-party CLI JSON documents that share one key set.

Trust / COI: About · Corrections. SEO Health is a commercial product from this team. The adapter below wraps a documented CLI bin. It is not a public HTTP SEO route on this host.

TL;DR

SEO API for developers work on this host is an adapter around a CLI bin. The registry lists seo-health, not an HTTP route. Six JSON documents reused the same top-level keys. Callers spawn the binary and parse. They should not invent a public REST endpoint.

Direct answer: Treat an SEO API for developers as a typed local wrapper: pin the package, spawn seo-health check --format json, keep stdout, and map transport, parse, schema, and domain failures to distinct errors. On 2026-09-14 the registry answered 200 for infinitegrowth@0.1.1 with bin seo-health. No public SEO HTTP API was observed.

The sample size is one registry GET plus six CLI JSON documents. That sample cannot establish a public HTTP SEO route, and it does not prove that callers should skip schema validation. An SEO API for developers record that drops the bin name is no longer replayable.

What you will learn

• Which registry fields were present and which were empty
• Which nine top-level keys every live document shared
• Why the wrong npx argv never reaches child_process
• How gate.mjs exits map onto adapter error classes
• Where this SEO API for developers page stops and a lockfile page begins

What an SEO API for developers actually wraps

Key definition: An SEO API for developers is a local adapter that spawns the documented CLI, preserves original fields, and returns a discriminated result. It does not certify rankings. It does not invent an undocumented HTTP path on infinisynapse.com. Its useful output is a typed object plus the child exit the caller recorded.

Node.js child process API is the platform reminder that execFile talks to a binary, not to a URL. That page does not grade this host and does not define a public SEO route.

People open an SEO API for developers when they already have Node and want a function, not a dashboard. They do not need a fabricated OpenAPI host. They need a timeout, a maxBuffer, and a parser that refuses to treat process 0 as a page pass.

MDN URL API is why the adapter should reject a non-HTTPS input before spawn. That check is input hygiene. It is not a keep vote.

The adapter returns typed rows, not a hosted HTTP product. A caller may later post those rows into an InfiniSynapse Server API long-task workspace and consume SSE; the API is not a public SEO REST route on this host.

Bin, not route

The 2026-09-14 registry GET returned HTTP 200. dist-tags.latest was 0.1.1. Versions were 0.1.0 and 0.1.1. bin.seo-health pointed at dist/bin/seo-health.js. license, repository, and homepage were empty. Engines asked for Node >=20. Unpacked size was 42574 bytes across 35 files. Maintainer was zhuyuejoey. An SEO API for developers that documents an HTTP path instead of that bin is inventing a surface.

Shared keys, six documents

Every live document in the desk exposed url, page, onPage, issues, images, keywords, speed, seoData, and cached. page carried title, description, canonical, and wordCount. issues[].status values seen were good and warning. No error appeared in this sample.

Registry and six documents on 2026-09-14

Node v22.18.0 was on PATH. The package pin was infinitegrowth@0.1.1. The desk did not markdown-link the registry page here; that link belongs on the npm sibling.

Every warning was Image Alt Text (2/5). cached was false. An SEO API for developers that maps child exit 0 onto ok: true would have marked all six as passed. Reproduce the spawn on one URL first, then compare keys across the six files before you add retries.

Figure: Two series from the same desk. Shared key count is not process exit. Neither series is a ranking score.

Empty registry fields stay empty

Do not invent a license or a repository URL because the adapter needs a citation. Record empty as empty. Created was 2026-08-03T10:10:51.959Z. Last-modified was Mon 03 Aug 2026 15:43:35 GMT. Those stamps are registry facts, not a hosted SEO HTTP service.

Fixture exits still apply

Local gate.mjs on the same day exited 1 on red.fixture.json (SEO_RED Title Length), 2 on malformed.fixture.json (SEO_CONTRACT missing_result_arrays), 0 on warn and good, and 2 when no path was given. An SEO API for developers should expose those four outcomes as distinct error classes. Callers who collapse them into one AdapterError will not know whether to fix argv, JSON, or the page.

How to reproduce the spawn

Pin the package. Spawn the bin. Parse stdout. Do not call an invented host.

node --input-type=module -e '
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const run = promisify(execFile);
const { stdout } = await run("npx", [
  "--yes", "-p", "infinitegrowth@0.1.1",
  "seo-health", "check", "--format", "json", "--lang", "en",
  "https://infinisynapse.com/en/tool/seo-ci-cd"
], { timeout: 120000, maxBuffer: 10 * 1024 * 1024 });
const doc = JSON.parse(stdout);
console.log(Object.keys(doc).join(","));
'

As of 2026-09-14 that spawn left process 0 and one warning row inside the JSON. An SEO API for developers still has to read issues[].status. json.loads in Python, or JSON.parse here, is the evidence step. The child exit is not.

Spawn without -p is a transport failure: the child printed error: unknown command 'seo-health' and returned 1. Put -p in the adapter.

RFC 9110 HTTP semantics is cited for timeout and status vocabulary, not because this adapter is an HTTP server.

How to reproduce the fixture

Keep the gate beside the adapter. Callers who only wrap execFile still need the same contract.

node gate.mjs red.fixture.json; echo exit:$?
# SEO_RED Title Length · exit 1
node gate.mjs malformed.fixture.json; echo exit:$?
# SEO_CONTRACT missing_result_arrays · exit 2

JSON Schema specification is why a typed wrapper should still validate arrays before it reads status. A cast-to-interface that skips the arrays is how malformed JSON becomes a fake pass.

An SEO API for developers that swallows JSON.parse exceptions and returns ok has already failed closed in the wrong direction.

Why spawn is not an HTTP product

OpenAPI Specification describes HTTP APIs. This page does not publish one. If you later wrap the adapter behind your own authenticated route, that is your service. It is not an observed InfiniSynapse SEO REST endpoint.

OWASP Input Validation Cheat Sheet is why stdout from the child is untrusted until parsed. Validate url and the result arrays. Do not concatenate stderr into a success object.

Transport success only proves that a process returned data. It does not prove the page passed the checks inside that data. For an SEO API for developers, that split is the entire adapter contract.

Distinct error classes

Use separate names for spawn timeout, invalid JSON, missing arrays, and a valid document with status: "error". The desk used exit 2 for contract failures and exit 1 for content reds. Keep that distinction so on-call does not start with a guess.

Timeout and maxBuffer

The example uses 120 seconds and a 10 MB buffer. Those numbers are a starting policy, not a measured SLA. A hung child that is treated as success is worse than a timeout error.

Where this page stops

This page owns the adapter shape and the registry-plus-keys desk. Surfaces that fail differently live on siblings. An SEO API for developers write-up does not become a lockfile walkthrough on this URL.

Package identity, empty license fields, and the -p pin belong on the npm sibling. Schema-first validation belongs on the JSON sibling. Record the command, the package version, the UTC date, the target URL, the original fields, and the child exit.

Keep stdout on disk even when the adapter later returns a domain error. A red result without a file creates an argument. A retained file creates a repair queue.

The SEO CI/CD complete guide owns the shared decision model. Open that hub when the question is the merge rule rather than the function signature. An SEO API for developers only answers how a caller gets a typed result from the bin.

Adoption in four reviewable commits

Do not land types, spawn, schema, and a caller in one opaque commit. An SEO API for developers is easier to revert when each change leaves a file. Keep the observed keys in the type, and leave ranking language out of the return object.

Type the report first

Commit a type that requires url and at least one of issues or onPage as arrays. Reject a document that only has url. The malformed fixture already proves that path.

Wrap one spawn

Call execFile with a timeout. Archive stdout. Do not start with 500 URLs. The smallest useful adapter checks one public URL and returns a discriminated result.

Map fixture exits

Feed red, malformed, warn, and good files through the same function. Record 1, 2, 0, and 0. An SEO API for developers rollout that only demos the happy path hides the contract.

Require the caller check

A library that can throw and a job that ignores the throw is telemetry. Make the named check required. Keep the raw JSON beside the typed result.

Failure modes worth a typed result

Invented HTTP route. The registry listed a bin. This desk did not observe a public SEO REST path. An SEO API for developers that documents one is inventing a surface.

Child exit as domain success. Six live documents exited 0 with a warning. An SEO API for developers that returns passed: true on exit 0 is wrong.

Wrong argv. Forgetting -p yields unknown command 'seo-health'. Put the working form in the SEO API for developers function, not in a wiki.

Schema skipped. JSON.parse success is not array validity. The malformed fixture exited 2 with only a url.

Secrets in argv. Do not pass a CLI key for default check. Deep commands stay out of the default SEO API for developers adapter.

Cluster guides

Use this page for the spawn-and-parse contract, then open the surface you actually operate.

Frequently Asked Questions

Does the typed local adapter require a login?

No. Default check, audit, and links do not need a CLI key. eeat, aivisibility, and gsc do. Keep those deep commands out of the default SEO API for developers function unless a named owner accepts the spend.

How should the client classify malformed JSON?

Fail closed. The desk used exit 2 for a missing issues array. Keep stderr and any partial stdout. Malformed data is not a warning, because an SEO API for developers cannot prove the required checks ran.

Can transport exit status determine domain success?

No. Six live documents exited 0 while Image Alt Text was warning. Parse issues[] and onPage[]. Preserve name and status. Then apply the caller rule.

Does this design expose an official Google score?

No. An SEO API for developers returns traffic-light rows as typed data. Those rows are not a Google grade, an index promise, or a rank forecast.

Do we claim a public SEO HTTP API exists?

No. The registry listed a CLI bin. This rewrite spawned that bin. It did not call an undocumented InfiniSynapse SEO REST endpoint.

Conclusion

Use an SEO API for developers when the job is to spawn the documented bin, keep the JSON, and return distinct errors. The 2026-09-14 desk shows an empty license field, a seo-health bin, and six documents that share one key set while leaving exit 0 beside a warning. Close the SEO API for developers file when the spawn command, the version, the keys, and the mapped errors are still visible. A typed adapter is more useful than an unsupported HTTP claim.

Open the InfiniSynapse web app only when a signed-in deep command is in the caller. The adapter still ends at spawn, parse, and a discriminated error.