docs(v2): API reference and response corrections (2/3)

[SohamRatnaparkhi]

The V2 API reference had wrong defaults, response shapes, and endpoint behavior, plus repeated notes that said the same thing two or three times. This PR keeps the original explanations and examples, fixes those claims against the backend, and removes the repetition.

Scope: api-reference/v2/ and essentials/v2/api-results.mdx. This is the API part of PRO-2457, next to Guides #309 and Cookbooks #311.

Fixes checked against the code:

• SDKs: removed the Versioning section (no X-API-Version header exists). Polling now uses ready_for_ingestion.
• Databases: the stats row now says it returns row counts. Added the metadata schema read endpoint. Removed the false MongoDB index warning on schema updates.
• Ingest Context: the app_knowledge example uses kind, provider, external_id and fields. Item database and collection are optional.
• Update Source Metadata: tenant replaced by database.
• Query overview: the personalized recipe says to list both collections in collections when shared docs live elsewhere.
• Error Responses: troubleshooting no longer names the deprecated tenant_metadata.

Repetition removed:

• Query: the alias Note and the Default Behaviors block that restated the field table.
• Duplicate warnings on Delete Database, Delete Collection, and Update Metadata Schema.
• Duplicate notes on Submit Feedback and Error Responses.

Connector and webhook pages were read line by line. A new Webhooks: Overview page, first in the Webhooks group, lists every webhook endpoint including the signing-secret calls, the typical sequence, and how deliveries are signed and retried. The connector pages link to the custom instructions section of the Connectors guide.

Navigation: the API Reference sidebar now opens with a "Start here" group holding the four calls most integrations are built on (Create Database, Ingest Context, Ingestion Status, Query) plus the overview. The resource groups still list every endpoint, so browsing by resource works as before. SDKs and Error Responses move to a Reference group. The overview page leads with the same four calls.

Latest pass, applying the same principles as the Guides:

• Every endpoint now shows Python SDK, TypeScript SDK, and cURL. The 13 connector pages were cURL-only and the 7 webhook pages had no examples; Update Metadata Schema, Update Source Metadata, and one Ingest Context example used raw HTTP in their SDK tabs. Every new SDK call was run against a local mock server and type-checked against SDK 2.1.7, and sends the same request as its cURL.
• 40 routine Note, Info, Tip, and Warning boxes are plain text now. Warnings remain only where data or access is at risk.
• The overview drops tables and setup code that repeat other pages (2,202 words to 1,655) and groups the endpoint inventory by resource.
• Error Responses says that both SDKs already retry 408, 429, and 5xx with exponential backoff, and how to raise the count.
• No "material", no per-user framing of collections; connector examples write to one company_docs collection.
• Merged with main after docs(ingest): blank scans and text-free photos fail with E2002 (PRO-2456) #313 and docs(app-sources): clarify classes, threads, and ingestion flow #315.

Validation: MDX compile, Mintlify build validation, broken links, hygiene, and the stale-claim check all pass.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cortex-ai	🟢 Ready	View Preview	Oct 8, 2026, 7:16 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

✅ Mintlify Hygiene

No issues found.

[openhack-agent]

✅ OpenHack Summary

Security review of docs(v2): API reference and response corrections (2/3). 52 changed files; 0 findings at or above the low reporting threshold.

0   0   0   0

Confidence Score: 5/5

No reportable security findings were detected in this scan.

Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage.

Files Needing Attention: None

Important Files Changed

• api-reference/v2/endpoint/add-connector-resource.mdx (modified)
• api-reference/v2/endpoint/configure-connector.mdx (modified)
• api-reference/v2/endpoint/connector-resources.mdx (modified)
• api-reference/v2/endpoint/connectors-overview.mdx (modified)
• api-reference/v2/endpoint/create-connector.mdx (modified)
• api-reference/v2/endpoint/create-tenant.mdx (modified)
• api-reference/v2/endpoint/delete-collection.mdx (modified)
• api-reference/v2/endpoint/delete-connector-resource.mdx (modified)
• api-reference/v2/endpoint/delete-connector.mdx (modified)
• api-reference/v2/endpoint/delete-source.mdx (modified)
• api-reference/v2/endpoint/delete-tenant.mdx (modified)
• api-reference/v2/endpoint/delete-webhook.mdx (modified)
• api-reference/v2/endpoint/discover-connector-resources.mdx (modified)
• api-reference/v2/endpoint/fetch-content.mdx (modified)
• api-reference/v2/endpoint/get-connector-status.mdx (modified)
• api-reference/v2/endpoint/get-connector.mdx (modified)
• api-reference/v2/endpoint/get-webhook-delivery.mdx (modified)
• api-reference/v2/endpoint/get-webhook.mdx (modified)
• api-reference/v2/endpoint/ingest-context.mdx (modified)
• api-reference/v2/endpoint/list-connector-providers.mdx (modified)
• api-reference/v2/endpoint/list-connectors.mdx (modified)
• api-reference/v2/endpoint/list-documents.mdx (modified)
• api-reference/v2/endpoint/list-sub-tenants.mdx (modified)
• api-reference/v2/endpoint/list-tenants.mdx (modified)
• api-reference/v2/endpoint/list-webhook-deliveries.mdx (modified)

View all 52 changed files

Last reviewed commit: e75296c · View review on OpenHack

---

TIP: Mention @openhack-agent in a PR comment to request a review or ask a question. Use @openhack-agent fix all for every finding, or @openhack-agent fix unresolved threads for open review threads only.

[openhack-agent]

OpenHack reviewed this commit. See the OpenHack Summary for the confidence score and fix actions.

[SohamRatnaparkhi]

@greptileai Please review the current head, including the V2 OpenAPI changes.

[greptile-apps]

Confidence Score: 5/5

[Low risk] Documentation corrections and clarifications across API reference.

The PR appears safe to merge; no new actionable issue or outstanding previous finding remains.

Summary

The PR corrects v2 API request and response guidance, examples, and OpenAPI schemas, then makes retrieval results easier to approach before the advanced graph fields.

• Aligns ingestion, query, status, metadata, and error documentation with the revised examples and specification.
• Introduces context, chunks, and connected subgraphs in plainer language while retaining the detailed response reference in an expandable section.
• Greptile automatically discovered a related ticket that helped explain the purpose of this PR: it calls for a final pass on v2 API response examples and the OpenAPI specification.

_{Reviews (4) · Last reviewed commit: "docs(v2): explain API results before adv..." · Reviewed by Greptile}

[SohamRatnaparkhi]

@greptileai Please review the current head.

• The PATCH metadata-schema example now adds a VARCHAR field without dense/sparse search flags. Ignored enable_match fields are also removed from all OpenAPI examples.
• Query defaults and unsupported filtering flags in the linked Guides are corrected in the separate Guides PR docs(v2): Guides cleanup (1/3) #309, as requested by PRO-2457's three-PR scope. Guides is the first stage; the API Reference is the second. Keeping those guide files in docs(v2): Guides cleanup (1/3) #309 avoids duplicating changes across the independent PRs.
• The subgraph route statement is verified against published Python and TypeScript SDK 2.1.7, rather than inferred from this older OpenAPI snapshot: Python hydra_db/context/raw_client.py calls context/subgraph with id in query parameters; TypeScript dist/api/resources/context/client/Client.js does the same. The backend registers both /context/:id/subgraph and /context/subgraph. The wording now identifies the verified SDK version explicitly. The OpenAPI page's path route and the SDK's query-string route are both supported.
• Rendered-preview inspection also exposed success examples containing a non-null error. Their schemas now model error as an object or null and use a null success example. Scope aliases carry matching values, and the ingest sample's success count matches its item count.

Mintlify validation, MDX/frontmatter, Python/JSON parsing, and local schema reference checks pass.

[SohamRatnaparkhi]

@greptileai Please reassess the current head and the inline responses. The fetch schema now accepts the null fields emitted by content and URL modes; those samples pass schema validation. SDK route and separate Guides-scope findings have implementation evidence in their threads.

[SohamRatnaparkhi]

@greptileai Please review current head 4d42afe. This pass explains context and chunks before advanced terms, clarifies relationship/subgraph terminology, and keeps the full API Results response reference in an expandable section before the prompt-formatting examples. It preserves request examples and endpoint contracts. Local build validation and hosted validation, hygiene, and link checks pass.