Repository navigation
OpenAPI schema for POST /api/v3/packages does not reflect paginated and polymorphic response #2331
Description
The current OpenAPI schema incorrectly documents the response structure of the POST /api/v3/packages/ endpoint.
The schema currently lists a 201 response as a direct mapping to #/components/schemas/PackageV3:
"/api/v3/packages/": {
"post": {
"operationId": "v3_packages_create",
"tags": [
"v3"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PackageQuery"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/PackageQuery"
}
},
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/PackageQuery"
}
}
}
},
"security": [
{
"cookieAuth": []
},
{
"tokenAuth": []
},
{}
],
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PackageV3"
}
}
},
"description": ""
}
}
}
},However, the actual API response is paginated, and the contents of the results array vary depending on request parameters (such as the details boolean option), so the response can also contain a list of PURL strings, instead of PackageV3 objects.
The response also has an incorrect status code in the schema (actual status code is 200).
This causes automated client generators to fail to parse the actual API responses because they expect a 201 flat object instead of the 200 paginated response structure.
Reacted by Sebastian Schuberth
Activity
TG1999 commentedon Jun 11, 2026
Please refer to:
https://github.com/aboutcode-org/vulnerablecode/blob/main/api_v3_usage.rst
refactor(clients): Patch schema and add workarounds
refactor(clients): Patch schema and add workarounds
sschuberth commentedon Jul 1, 2026
Thanks, but we need this to be reflected in machine-readable format in order to auto-generate client code.
refactor(clients): Patch schema and add workarounds
refactor(clients): Patch schema and add workarounds
refactor(clients): Patch schema and add workarounds
refactor(clients): Patch schema and add workarounds
refactor(clients): Patch schema and add workarounds
refactor(clients): Patch schema and add workarounds