Add a guide for using ISC APIs with AI coding assistants

[kbennett2000]

Adds a guide for developers building ISC integrations with an AI coding assistant, as proposed in #1180.

What it covers

docs/api/using-isc-apis-with-ai-coding-assistants.md, registered in sidebars.ts under isc_api_sidebar after Patch Requests, so it sits with its siblings (Getting Started, Authentication, Authorization, Versioning). Sections:

1. Give the assistant the specification, not the reference page. What an automated fetch actually returns from a guide page, an API reference page, and a legacy V3/Beta reference page — and where the specs live.
2. Choosing a version. Per-service versioning, X-SailPoint-Experimental on the operations that declare it, and what it means when an assistant emits a /v3/ or /beta/ path.
3. Finding the scopes an operation needs. The per-operation security block and x-sailpoint-userLevels.
4. The token endpoint is not an operation in the specification. Where /oauth/token actually appears, and the real client-credentials request shape.
5. Verify a generated request before you run it. The servers prefix trap, and a script that resolves an operationId to its path, scopes, user levels and parameters.

It points at the MCP Server docs up front for readers who want conversational access rather than generated code, so the two do not compete.

Two corrections to what I originally proposed

I checked my own claims from #1180 against the spec files before writing, and two did not hold. Flagging both, since the issue text is wrong on them:

• "The experimental header beta requires" is not a thing. Of the 358 operations in deref-sailpoint-api.v3.yaml, none declare X-SailPoint-Experimental; of the 559 in deref-sailpoint-api.beta.yaml, one does (listAdministratorsAccessRequestStatus). It is declared on 207 of the 880 operations in deref-sailpoint-api.yaml, per operation rather than per version. The page says that instead.
• The rendered reference does not return "almost nothing". It returns the method, path, summary and response codes; what is missing is the parameters, the request/response schemas, and the Authorization block. The page states the narrower, accurate version.

I also led with per-service versioning rather than framing the page as a V3-vs-Beta choice, since api-versioning-strategy.md now marks Beta, V3 and v202X legacy (supported to Q2 2028, end-of-life Q1 2029). V3 and Beta are covered as what an assistant tends to emit from stale training data, with the operationId mapping for finding the current equivalent.

Happy to adjust any of this if the DevRel team would rather frame it differently.

AI disclosure and validation

Per the AI Usage Policy: this page was drafted with AI assistance. Every factual claim was verified before it went in, and none of it was taken on the assistant's word. What was checked, and how:

Checked against sailpoint-oss/api-specs (parsed, not grepped — counts are over the dereferenced/ bundles):

Claim in the page	How it was verified
Current API: 597 paths, 880 operations	Parsed paths in idn/sailpoint-api.yaml
207 of 880 operations declare X-SailPoint-Experimental, required: true	Parsed operation parameters
0 of 358 V3 operations, 1 of 559 Beta operations declare it	Parsed deref-sailpoint-api.v3.yaml and .beta.yaml — the thin roots must be dereferenced first, which is why an earlier grep of the roots returned 0 for both
Scopes live in a per-operation security/userAuth block beside x-sailpoint-userLevels	Read idn/apis/access-profiles/paths/access-profiles-v1.yaml
16 operations declare no security block and inherit sp:scopes:all	Counted operations with no security key against the root default
/oauth/token is absent from paths in all three specs, and present only as securitySchemes.*.flows.*.tokenUrl	Parsed paths and components.securitySchemes
The servers prefix differs per spec ("", /v3, /beta)	Read servers[].url in each root
349/358 V3 and 519/559 Beta operationIds have a V1/V2 twin in the current spec	Set comparison of operationIds across the three bundles
7,707 internal $refs remain in the bundled current spec	Counted $ref: '#/...' occurrences
The current root is self-contained; the V3 and Beta roots reference external path files	idn/sailpoint-api.yaml is byte-identical (sha256) to dereferenced/deref-sailpoint-api.yaml; the legacy roots hold 280 and 437 external $refs

Checked by fetching the live pages (robots.txt is Allow: /):

Claim	What the fetch returned
A guide page returns its full content	/docs/api/authentication — ~31 KB of extractable text
An API reference page returns method, path, summary and response codes only	/docs/api/list-access-profiles-v-1 — GET /access-profiles/v1 and the summary are present; idn:access-profile:read, sp:scopes, oauth2 and securitySchemes appear nowhere in the HTML, including inline scripts
A legacy reference page returns a redirect stub	/docs/api/v3/list-access-profiles — a ~700 byte redirect to /redoc/sailpoint-api-v3-light.html#tag/..., and that target is a single ~9 MB page for the whole API
The release asset URL resolves	releases/latest/download/deref-sailpoint-api.yaml returns 200

Both code samples were executed against the real specs before being pasted in. The listing snippet returns exactly 207 operationIds. The verification script was corrected after its first version silently dropped limit, offset and count — it did not follow the internal $refs — which is the failure the page now warns about.

Checks

• Built locally with npm run gen-api-docs-all && npm run build against specs synced from sailpoint-oss/api-specs; the page renders and appears in the sidebar.
• npx prettier --check passes on the new markdown file. sidebars.ts reports pre-existing formatting differences unrelated to this change (it is unformatted on main today); the 4 added lines match the surrounding style, and I have deliberately not reformatted the rest of the file to keep the diff reviewable.
• Every link in the page resolves. Tenant placeholders use {tenant} and example-tenant, which .slinkignore already excludes.
• No credentials appear anywhere, and no request is made against a real tenant.

Refs #1180

---

🤖 Generated with Claude Code

[CLAassistant]

All committers have signed the CLA.