feat(api-docs): Improve SDK API documentation

[khvn26]

Thanks for submitting a PR! Please check the boxes below:

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Contributes to #6341.

In this PR, we improve the SDK API documentation, decoupling it from the flagsmith-engine's legacy code.

• Add flagsmith_schemas integration for OpenAPI generation
• Support TypedDict in schema generation
• Ensure schema refs are not overwritten by other schemas with the same name
• Add OpenAPI server definitions and update operation IDs for SDK endpoints
• Generate securitySchemes correctly
• Add integration tests for SDK API schemas
• Regenerate static Edge API docs from the new SDK schema

How did you test this code?

CI, make -C docs serve.

How to review this PR

This PR contains three distinct types of changes:

1. Python code architecture changes

The backend moves from Django REST serializers and legacy engine's Pydantic models to using flagsmith_schemas as the single source of truth for API contracts.

Key files to examine:

• api/api/openapi.py: existing tooling for Pydantic models repurposed for TypedDicts. Added generation code for authentication classes used in our views
• api/environments/identities/serializers.py & views.py: Modified to align with schema definitions
• api/tests/integration/sdk/test_sdk_api_schemas.py: New integration tests that validate actual API responses against flagsmith_schemas.api types using Pydantic's TypeAdapter

What got deleted and why:

• api/environments/sdk/schemas.py: Redundant, replaced by flagsmith_schemas
• api/util/pydantic.py: Custom Pydantic utilities no longer needed

2. OpenAPI spec generation tooling

New infrastructure for generating SDK API documentation from the backend code.

Core components:

• sdk/openapi.yaml: The generated OpenAPI spec describing SDK endpoints. Can be ignored unless you're really interested in how generation works.
• api/openapi-filter-flagsmith-sdk.yml: Filter configuration that extracts only SDK endpoints from the full API spec
• api/Makefile & docs/Makefile: New generate-sdk-api-docs target that runs the generation pipeline

Generation flow to verify:

1. Backend generates full OpenAPI spec including all endpoints
2. Filter applies to extract only SDK endpoints (those without sdk tag get removed)
3. Result written to sdk/openapi.yaml
4. Docusaurus consumes this to generate MDX documentation (make -C docs build)

3. Documentation migration

Complete replacement of Edge API docs with SDK API docs, plus fixing all internal references. This part is responsible for a significant chunk of the diff as the generated docs are replaced and shuffled around.

Documentation structure change:

• Old path: /docs/edge-api/* (6 files deleted)
• New path: /docs/sdk-api/* (6 files created) — suggest to ignore these and check the deployed, or locally served, docs instead.
• The content is now auto-generated from sdk/openapi.yaml rather than hand-written schema

Link updates across the docs:

• docs/vercel.json: Redirects from /edge-api/* to /sdk-api/* paths
• Various .md files: Updated references from "Edge API" to "SDK API"
• docusaurus.config.ts: Plugin configuration for the new SDK API documentation

Follow-up issues

• Deal with extra fields in SDK API responses #6625 — basically, we should review the API schemas together, and shave off the extra fields, or add the ones that are really necessary to the schemas, or both of the above.
• Implement /api/v1/bulk-identities in Core API #6628 — eliminate discrepancy between Core and Edge APIs. More context here.
• Restrict Token authentication in Core API #6629 — surfaced after adding autogeneration for OpenAPI security schemes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs	Ignored	Preview	Feb 2, 2026 0:56am
flagsmith-frontend-preview	Ignored	Preview	Feb 2, 2026 0:56am
flagsmith-frontend-staging	Ignored	Preview	Feb 2, 2026 0:56am

[github-actions]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-e2e:pr-6626	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-frontend:pr-6626	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-api-test:pr-6626	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-api:pr-6626	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith:pr-6626	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-private-cloud:pr-6626	Finished ✅	Results ✅

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.18%. Comparing base (a0d5aa9) to head (72412e2).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6626   +/-   ##
=======================================
  Coverage   98.18%   98.18%           
=======================================
  Files        1295     1294    -1     
  Lines       46920    46994   +74     
=======================================
+ Hits        46067    46141   +74     
  Misses        853      853           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[emyller]

Looks solid! Non-blocking comments.

[emyller]

LGTM!