SEO audit API: first request, JSON findings, and next steps

What an SEO audit API does and when it fits

An API makes an audit available to software over HTTP. Instead of reading a report on screen, your program receives JSON that it can inspect, save, or turn into a task list. Technical checks can cover response codes, metadata, indexability signals, structured data, links, and crawler access. The exact checks and crawl scope depend on the endpoint you choose.

Shipwork's audit endpoint starts from the submitted address, reads a bounded sample of public pages from outside your network, and runs the checks that apply. One request can inspect several sampled pages; submitting the home page does not mean every URL on the domain was crawled. The result includes the sampled URLs so you can see the scope of that run.

A JSON workflow is useful when you want to review evidence in your own dashboard or add a deliberate audit step to an existing process. If you only need to inspect a site manually, the browser audit gives you the same starting task with a readable interface. An API removes the manual transfer of data; it does not remove the need to understand a finding.

Keep technical audit data separate from keyword rankings, backlink indexes, and Search Console performance. Those answer different questions. A canonical check can report what a page declares, but it cannot establish which canonical Google selected. An audit score is a summary of supported checks, not a prediction of rankings or traffic.

Make your first SEO audit API request

Choose a public site you own or have permission to inspect. Start with one deliberate request while you learn the output and allowance. The public endpoint accepts a JSON body with a url field and requires no key to start:

curl -i -X POST https://shipwork.io/api/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

The -i option shows the HTTP status and headers along with the body. Check that status before interpreting the response as an audit. A rejected request, an exhausted allowance, or a connection failure is not evidence that the inspected site has an SEO problem.

This JavaScript example checks the HTTP response, parses the body, and verifies the audit's main collection before using it. Run it in a JavaScript environment that supports fetch and AbortSignal.timeout:

async function requestAudit(url) {
  const response = await fetch("https://shipwork.io/api/audit", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url }),
    signal: AbortSignal.timeout(120000)
  });
  if (!response.ok) {
    throw new Error("Audit request returned HTTP " + response.status);
  }
  const audit = await response.json();
  if (!Array.isArray(audit.results)) {
    throw new Error("Unexpected audit response; inspect it before processing");
  }
  return audit;
}

The timeout is a client choice, not a service guarantee. Slow sites and network conditions can change how long a run takes. If a request fails, inspect the cause before retrying: repeated requests may consume allowance and repeat work. In particular, an HTTP 429 should send you to the current allowance guidance rather than an immediate retry loop.

Use the API reference for current endpoints, request fields, and access limits, and the machine-readable API document when connecting software. This tutorial explains the audit workflow; the reference is the place to check the current contract before relying on it.

Read a JSON finding and verify it on the page

The audit response groups checks in results. Each group has an identifier, a label, and a findings list. The summary reports counts and sampled-page coverage; pagesSampled names the pages read, their status, and any reported skipped or failed fetch. Start with coverage: a result about three pages cannot justify a statement about three thousand.

The public free response is a preview. Some issue entries can have locked: true without the detailed message or fix. Preserve that state in your application. Treating a locked finding as an empty finding would make a partial report look complete. Informational notes and open issues also differ from confirmed failures.

This extraction keeps the check context and skips locked details explicitly. It creates a review list from returned issue messages; it does not automatically decide which deployment should fail:

const audit = await requestAudit("https://example.com");
console.log(audit.summary);
console.log(audit.pagesSampled);

const review = [];
let lockedIssues = 0;

for (const check of audit.results) {
  for (const finding of check.findings || []) {
    if (finding.locked) {
      lockedIssues += 1;
      continue;
    }
    if (finding.severity === "error" || finding.severity === "warn") {
      review.push({
        check: check.id,
        severity: finding.severity,
        message: finding.msg,
        suggestedFix: finding.fix
      });
    }
  }
}
console.table(review);
console.log("Locked issue details:", lockedIssues);

For each useful finding, identify the affected page from the returned evidence. Then verify the condition with the relevant method: fetch the URL for a response-code issue, inspect the page's head for a canonical declaration, or open the source and rendered views for missing content. A page that looks fine in your logged-in browser may respond differently to an outside request.

Prioritize by consequence and scope. A broken response on an important page deserves attention before cosmetic metadata changes. A warning may describe an intentional configuration. Record the page, the observed condition, your decision, and the change made. Use a later permitted run to confirm the fix, and compare equivalent pages and settings across runs.

Understand preview limits and deeper crawl coverage

A free SEO audit API still has resource and usage limits. Shipwork's public API uses the website's free allowance, and its free audit response is a preview. Consult the current reference and pricing before scheduling calls or building an application that depends on complete results. The absence of an API key requirement does not imply unlimited requests.

Sampling and rendering are separate limits. A sample can reveal a recurring template problem, but it can miss a URL using a different template. An HTML-based check can miss content added only by JavaScript. If that distinction matters, compare the raw response with a rendered view using the rendered check and read the JavaScript SEO guide for context.

Use a deeper crawl when the job requires checking a broader URL set, then inspect its coverage and time limits too. Keep a record of the URLs actually reached. A clean sample, a partial crawl, and a completed inventory are different levels of evidence.

Start with one address, inspect the JSON and coverage, verify a finding, and make a specific repair. That gives you a workflow you can trust before expanding its scope. For the current endpoint details, return to the API reference; for a manual first pass, run the browser audit.

Questions

Keep reading