API: OpenAPI schema does not match live responses (breaks strict output validation)

[khvn26]

The published OpenAPI schema (/api/v1/swagger.json) disagrees with actual API responses in several systematic ways. Any client that validates responses against the schema (e.g. the Flagsmith MCP server, which uses FastMCP's from_openapi output validation) fails on most endpoints. Found by crawling the MCP-tagged read endpoints against SaaS and validating each response against its declared schema.

1. Pagination next/previous typed string, returned null

Paginated responses declare next and previous as non-nullable string, but the API returns null when there is no adjacent page. Should be string, nullable (anyOf: [string, "null"]).

Affected: list_organizations, list_organization_groups, list_organization_invites, list_organization_roles, list_environments, list_project_features, list_project_segments, list_project_change_requests, list_feature_multivariate_options, list_feature_segments, get_environment_feature_versions (likely all paginated list endpoints).

2. Array-returning endpoints declared as a single object

The 200 response schema is the singular item serializer, but the endpoint returns a JSON array. Should be type: array, items: <object>.

• GET /organisations/{id}/projects/ (list_projects_in_organization)
• GET /projects/{id}/environments/ (list_project_environments)
• GET /projects/{project_pk}/features/{feature_pk}/code-references/
• GET /projects/{project_pk}/features/{id}/evaluation-data/

3. get_feature_external_resources: missing count

GET …/feature-external-resources/ returns {"results": []} but the schema marks count as required. Either the response should include the full pagination envelope or the schema should not require count.

4. owners / group_owners typed as integer IDs but expanded in responses

Read responses expand these to nested user objects ({id,email,first_name,last_name,last_login,uuid}), while the schema types them as array<integer>. Affects get_feature_flag and list_project_features (results[].owners[]); likely anywhere a feature is serialised for read.

Impact / workaround

The MCP server currently sets validate_output=False to avoid rejecting valid responses. We'd like to re-enable output validation once the schema matches reality.