generated: '2026-09-02' method: searched source: https://crawlgraph.com/docs/api also_from: openapi/_original/crawlgraph-openapi.json summary: >- CrawlGraph's upstream OpenAPI carries accurate schemas and ZERO examples — the FastAPI generator emits neither `example` nor `examples` on any request body, parameter or response. The provider publishes them anyway, on the docs page, and they are unusually complete: every operation ships a full request body, a full response body, and working curl / Python (requests) / Node (fetch) snippets, with the async job shown in all four of its states. This file indexes what the provider publishes and where, so the gap between "the spec has no examples" and "the provider documents every call" is visible as data rather than being scored as an absence. Values below are the PROVIDER'S OWN published examples, quoted as-is. Nothing was authored here. coverage: operations_in_spec: 6 operations_with_published_request_example: 4 operations_with_published_response_example: 5 operations_with_code_samples: 4 examples_in_the_openapi_itself: 0 languages: [curl, python-requests, node-fetch] note: >- free-key is documented with a request example in the Quickstart but no response body is shown — deliberately, because the key is emailed and "is never returned in this response". The gap-analysis poll operation has four documented response shapes (queued/running/completed/failed) and no request body, which is why the request and response counts differ. examples: - operation_id: v1_lookup_backlinks_api_v1_backlinks_post path: POST /api/v1/backlinks docs_section: '6. Endpoints — POST /api/v1/backlinks' docs: https://crawlgraph.com/docs/api request_example: | { "domain": "example.com", "release_id": "CC-MAIN-2026-04", "limit": 1000, "sort": "authority" } request_note: release_id, limit and sort are optional; defaults are latest release, 1000, authority. response_example: | { "domain": "example.com", "release_id": "CC-MAIN-2026-04", "release_label": "Apr 2026", "total_linking_domains": 4821, "returned": 1000, "results": [ { "linking_domain": "blog.foo.com", "num_hosts": 12, "tld": "com", "cg_authority": 84, "cg_rank": 1421 }, { "linking_domain": "news.bar.org", "num_hosts": 7, "tld": "org", "cg_authority": 71, "cg_rank": 9402 } ] } code_samples: [curl, python-requests, node-fetch] curl: | curl -X POST https://crawlgraph.com/api/v1/backlinks \ -H "Authorization: Bearer cg_live_..." \ -H "Content-Type: application/json" \ -d '{"domain": "example.com", "limit": 500}' - operation_id: v1_list_releases_api_v1_releases_get path: GET /api/v1/releases docs_section: '6. Endpoints — GET /api/v1/releases' docs: https://crawlgraph.com/docs/api request_example: null request_note: No parameters and no body. Not counted against quota. response_example: | { "releases": [ { "id": "CC-MAIN-2026-04", "label": "Apr 2026", "available": true }, { "id": "CC-MAIN-2025-50", "label": "Dec 2025", "available": true } ] } code_samples: [curl, python-requests, node-fetch] - operation_id: v1_gap_submit_api_v1_gap_analysis_post path: POST /api/v1/gap-analysis docs_section: '6. Endpoints — POST /api/v1/gap-analysis' docs: https://crawlgraph.com/docs/api request_example: | { "my_domain": "example.com", "competitor_domains": ["a.com", "b.com", "c.com"] } request_note: 1-5 competitor domains; the cap matches the dashboard. response_example: | { "job_id": "gap_a1b2c3", "status": "queued", "poll_url": "/api/v1/gap-analysis/gap_a1b2c3" } response_status: 202 code_samples: [curl, python-requests, node-fetch] code_sample_note: >- The published Python and Node samples are full submit-and-poll loops, not single calls — they show the 5-second poll interval and the completed/failed exit condition. - operation_id: v1_gap_poll_api_v1_gap_analysis__job_id__get path: GET /api/v1/gap-analysis/{job_id} docs_section: '6. Endpoints — GET /api/v1/gap-analysis/{job_id}' docs: https://crawlgraph.com/docs/api request_example: null response_examples_by_state: running: | { "job_id": "gap_a1b2c3", "status": "running", "started_at": "2026-04-27T12:34:56Z", "progress_pct": 42 } completed: | { "job_id": "gap_a1b2c3", "status": "completed", "completed_at": "2026-04-27T12:36:18Z", "result": { "my_domain": "example.com", "competitor_domains": ["a.com", "b.com", "c.com"], "gaps": [ { "linking_domain": "x.com", "found_on": ["a.com", "b.com"] } ], "total_gaps": 1284 } } failed: | { "job_id": "gap_a1b2c3", "status": "failed", "error": { "code": "internal_error", "message": "..." } } note: >- Documenting the failed shape as well as the happy path is the useful part here — an agent polling this endpoint can branch on status without guessing the error envelope. - operation_id: v1_changes_api_v1_changes_get path: GET /api/v1/changes docs_section: '6. Endpoints — GET /api/v1/changes' docs: https://crawlgraph.com/docs/api request_example: 'GET /api/v1/changes?domain=example.com' response_examples_by_state: comparison_available: | { "domain": "example.com", "comparison_available": true, "from_release": { "id": "cc-main-2026-jan-feb-mar", "label": "Jan-Mar 2026" }, "to_release": { "id": "cc-main-2026-apr-may-jun", "label": "Apr-Jun 2026" }, "counts": { "from_snapshot": 4821, "to_snapshot": 4890, "added": 92, "removed": 23, "authority_moved": 17 }, "added": [ { "linking_domain": "new-reference.org", "num_hosts": 4, "cg_authority": 73 } ], "removed": [ { "linking_domain": "older-reference.net", "num_hosts": 2, "cg_authority": 61 } ], "authority_moved": [ { "linking_domain": "example-source.com", "from_authority": 52, "to_authority": 60, "delta": 8 } ], "truncated": false, "cap": 100000, "snapshot_caveat": "Common Crawl snapshots are periodic observations, not live link monitoring. Absence from a newer snapshot does not prove a page removed a link." } comparison_unavailable: | { "domain": "example.com", "comparison_available": false, "from_release": null, "to_release": { "id": "cc-main-2026-mar-apr-may", "label": "Mar-May 2026" }, "counts": { "from_snapshot": 0, "to_snapshot": 0, "added": 0, "removed": 0, "authority_moved": 0 }, "added": [], "removed": [], "authority_moved": [], "truncated": false, "cap": 100000, "message": "both indexed release artifacts are required for a comparison", "snapshot_caveat": "Common Crawl snapshots are periodic observations, not live link monitoring." } code_samples: [curl] note: >- comparison_available false is a successful 200 that STILL consumes a backlinks call. That is the trap on this operation and the docs state it plainly. - operation_id: request_free_key_api_v1_free_key_post path: POST /api/v1/free-key docs_section: '1. Quickstart' docs: https://crawlgraph.com/docs/api request_example: | { "email": "you@example.com" } response_example: null response_note: >- No response example is published, by design: "The key is NEVER returned in this response — only by email." The OpenAPI types the 200 as a bare object with no properties. code_samples: [curl] error_envelope_example: docs_section: '5. Errors' example: | { "error": "", "message": "", "request_id": "req_a1b2c3d4" } see: errors/crawlgraph-problem-types.yml gap_in_the_spec: finding: >- Every example above lives only in the HTML docs. The machine-readable spec at /api/v1/openapi.json carries none of them, so a client generated from the spec alone gets correct types and no idea what a real call looks like. Adding `examples` to the request bodies and 2xx responses would be a small, purely additive change to the FastAPI models and would move the spec's content score without changing a single route. affected_operations: 6 examples_present_in_spec: 0 x-evidence: - {url: 'https://crawlgraph.com/docs/api', status: 200, note: 'sections 1, 5 and 6 — every example above quoted from this page'} - {url: 'https://crawlgraph.com/api/v1/openapi.json', status: 200, note: 'OpenAPI 3.1.0 v1.2.2 — grep confirms zero example/examples keys'}