OpenAPI SDK readiness
Box Platform API OpenAPI spec score
Octri scored the public spec at https://raw.githubusercontent.com/box/box-openapi/main/openapi.json for what a code generator can do with it. This is a reading of the document, not a grade of the API.
297 operations · 310 models · 73 tags · OpenAPI 3.0.2
Scored 14 September 2026 · fingerprint 0f8794edec1c… · spec version 2024.0 · server api.box.com
Document last changed 14 September 2026.
Where the points went
Every rule, heaviest first, with what it cost this document and how much of the surface it touched. Open a row for the locations.
Successful responses declare a schema2.00.4 lost6 of 297 operations
Without a response schema every method returns `unknown`/`any`, so callers get no types and no autocompletion.
POST /oauth2/revoke`post_oauth2_revoke` declares a success response with no schema, so the generated method returns an untyped value.POST /metadata_cascade_policies/{metadata_cascade_policy_id}/apply`post_metadata_cascade_policies_id_apply` declares a success response with no schema, so the generated method returns an untyped value.PUT /skill_invocations/{skill_id}`put_skill_invocations_id` declares a success response with no schema, so the generated method returns an untyped value.DELETE /legal_hold_policies/{legal_hold_policy_id}`delete_legal_hold_policies_id` declares a success response with no schema, so the generated method returns an untyped value.DELETE /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}`delete_legal_hold_policy_assignments_id` declares a success response with no schema, so the generated method returns an untyped value.- 1 more, not listed here.
Shared models live in components and are $ref'd2.00.4 lost3 of 297 operations
Inline object schemas become anonymous per-operation types. The same model inlined in 20 operations generates 20 near-identical types instead of one.
copyInstanceOnItemCopy, displayName, fields, hiddenAn identical inline object (6 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.description, external_sync_identifier, invitability_level, member_viewability_levelAn identical inline object (6 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.address, target, triggersAn identical inline object (3 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.
Generated public names do not collide2.0Clean297 operations clean
When authored identifiers collapse to the same shared public name, the generator must silently rename one method; callers otherwise cannot predict the SDK surface from the spec.
Every path placeholder has a parameter1.5Clean297 operations clean
An undeclared `{id}` placeholder cannot become a typed method argument, so the generated request path is incomplete or uncompilable.
Every operation declares an operationId1.0Clean297 operations clean
Without one the generator synthesizes a name from the path, which changes whenever the path does. That is a silent breaking change for callers.
operationIds read as method names1.00.5 lost122 of 297 operations
The id becomes the method name. `ActionsActionsGet` generates `client.actions.actionsActionsGet()`; `getActions` generates `client.actions.get()`.
POST /oauth2/token`post_oauth2_token` reads better as `createPostOauth2Token` at the call site.POST /oauth2/token#refresh`post_oauth2_token#refresh` reads better as `createPostOauth2TokenRefresh` at the call site.POST /oauth2/revoke`post_oauth2_revoke` reads better as `createPostOauth2Revoke` at the call site.POST /files/{file_id}`post_files_id` reads better as `createPostFilesId` at the call site.PUT /files/{file_id}`put_files_id` reads better as `updatePutFilesId` at the call site.- 117 more, not listed here.
Operations carry a summary or description1.0Clean297 operations clean
Operation prose becomes the method's doc comment, the text an IDE shows on hover.
Request bodies are documented1.00.3 lost18 of 297 operations
Body field descriptions become the doc comments on generated parameters; without them the SDK ships undocumented arguments.
PUT /files/upload_sessions/{upload_session_id}`put_files_upload_sessions_id` has an undocumented request body, so every generated parameter for it will be comment-free.PUT /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo`put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo` has an undocumented request body, so every generated parameter for it will be comment-free.POST /files/{file_id}/metadata/{scope}/{template_key}`post_files_id_metadata_id_id` has an undocumented request body, so every generated parameter for it will be comment-free.PUT /files/{file_id}/metadata/{scope}/{template_key}`put_files_id_metadata_id_id` has an undocumented request body, so every generated parameter for it will be comment-free.PUT /files/{file_id}/metadata/global/boxSkillsCards`put_files_id_metadata_global_boxSkillsCards` has an undocumented request body, so every generated parameter for it will be comment-free.- 13 more, not listed here.
Failure responses are declared1.0Clean297 operations clean
Declared error schemas become typed errors. Without them every failure surfaces as an untyped generic error.
Operations are tagged1.0Clean297 operations clean
Tags drive namespacing. Untagged operations fall back to a path segment, producing lopsided or `misc` namespaces.
No duplicate or equivalent paths1.0Clean187 paths clean
Paths differing only in parameter NAME are the same route to a server; the generated SDK ends up with two methods that call the same endpoint.
Authentication is described1.0CleanDeclared
Security schemes generate the SDK's auth configuration. A spec without them produces a client with no way to authenticate.
Parameters explain their purpose0.75Clean297 operations clean
Parameter descriptions become IDE hints on generated method arguments; bare names force SDK users back to the API reference.
A server URL is declared0.5CleanDeclared
Without a server URL the generated client must ship with an empty or placeholder base URL, adding setup work and easy production misconfiguration.
What 8.4 means for an SDK
A strong reading, and the three rules that decide most of it.
A generator has what it needs here: typed methods, named models and doc comments that say something. What is left is polish, and it can wait until after the first release.
Three rules carry six of the 10 points between them. On this document they took 0.85.
−0.4
Successful responses declare a schema
6 of 297 operations
−0.4
Shared models live in components and are $ref'd
3 of 297 operations
Clean
Generated public names do not collide
297 operations clean
What to change first
Every rule that deducted, in the order they cost.
Successful responses declare a schema
Give the success response a schema, or a $ref to one in components. A 204 needs nothing. Inside Octri this one has a one-click fix.
Shared models live in components and are $ref'd
Move the shape into components.schemas once and $ref it from each operation that returns or accepts it.
operationIds read as method names
Name the id for the action, not the route. The audit suggests one per operation and can apply it. Inside Octri this one has a one-click fix.
Request bodies are documented
Describe the body, or the fields inside it. Field-level prose is the one that reaches the SDK's arguments. Inside Octri this one has a one-click fix.
The spec at raw.githubusercontent.comis public. Octri keeps the `info` block, the score, and up to five sample finding locations per rule. The document itself is not stored and is not served from here. The audit predicts what an SDK generator can do with the description; it is not a security review, an uptime measurement or a critique of the API’s design. This page is not affiliated with Box Platform API or Box, Inc.