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

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ready	Preview	Comment	Oct 22, 2025 1:09pm

Pull Request Review: Update guard API docs to include file upload and multipart support

Summary

This PR updates the OpenAPI documentation for the /api/guard endpoint to reflect the recently added PDF file upload functionality. The changes align the API documentation with the SDK implementation that already supports file uploads.

Code Quality and Best Practices

Strengths:

• The OpenAPI specification is well-structured and follows standard conventions
• The addition of multipart/form-data content type properly coexists with the existing application/json type
• Good use of required fields to clarify that text is mandatory while file is optional
• The description has been appropriately updated to mention 'Supports both text and PDF file analysis'

Suggestions:

1. Schema validation: Consider adding more specific constraints to the file parameter (e.g., max size limits in the documentation)
2. Clarify text field behavior: The description states 'can be empty string when file is provided' but the schema marks text as required, which might be confusing

Potential Issues

1. Inconsistent required field logic (docs/openapi.json:266):

   • The schema marks text as required but description says it can be empty when file is provided
   • Recommendation: Either make text optional and update validation logic, OR clarify that text is always required but may be empty

2. Missing file format validation documentation:

   • No explicit documentation about accepted MIME types, maximum file size, or behavior when both text and file are provided

Performance Considerations

1. Multipart parsing overhead: Ensure the backend has proper streaming/buffering for large files and timeouts are configured appropriately
2. Consider documenting expected response times for file vs text analysis and any rate limiting differences

Security Concerns

1. File upload security (docs/openapi.json:273-275):

   • Good: The error example shows file type validation exists
   • Consider documenting: Maximum file size limits to prevent DoS, virus scanning, and file content validation beyond MIME type checking

2. Potential attack vectors to ensure backend handles:

   • PDF bombs (maliciously crafted PDFs that expand to huge sizes)
   • PDF with embedded executables
   • MIME type spoofing (validate actual file content, not just Content-Type header)

Test Coverage

Current state:

• SDK (sdk/typescript/src/index.ts:214-313) already implements file upload support
• CLI (cli/src/commands/guard.ts:27-45) has --file flag implementation
• Missing: No test coverage in sdk/typescript/tests/guard.test.ts for file upload scenarios

Recommendations: Add tests for PDF file upload, non-PDF file rejection, and handling both text and file parameters

Documentation Suggestions

1. Add examples section to show multipart usage with both textOnly and fileOnly scenarios
2. Verify that docs/content/docs/rest-api/guard.mdx auto-generates from openapi.json
3. Consider adding a usage guide with cURL examples for file uploads

Positive Highlights

1. Consistency: The changes align perfectly with the existing SDK implementation
2. Backward compatibility: Adding multipart support does not break existing JSON-based usage
3. Error handling: Good addition of the invalidFile error example
4. Clear commit message: Well-structured with bullet points explaining each change

Action Items

Required before merge:

• Clarify the text field requirement logic (required vs optional with empty string)

Recommended for follow-up:

• Add test coverage for file upload scenarios
• Document file size limits and constraints
• Add security notes about file validation
• Consider adding request/response examples for multipart requests

Final Verdict: Approve with Minor Suggestions

The PR successfully documents the file upload functionality and maintains consistency with the implementation. The changes are minimal, focused, and do not introduce breaking changes. Address the text field requirement clarification, and consider the test coverage suggestions in a follow-up PR.

Great work aligning the documentation with the SDK implementation!

PR Review: Update guard API docs to include file upload and multipart support

Summary

This PR updates the OpenAPI documentation to reflect the recent addition of PDF file upload support to the /api/guard endpoint. The changes align the documentation with the SDK implementations that already support this feature.

Code Quality and Best Practices

Strengths:

• Clean, minimal changes focused on documentation updates
• Consistent formatting and structure with existing OpenAPI spec
• Proper use of OpenAPI 3.x schema definitions for multipart/form-data
• Good alignment with REST API conventions

Observations:

• The OpenAPI changes follow established patterns from the codebase
• Documentation changes are concise and informative
• The PR maintains consistency across guard.mdx and redact.mdx files

Potential Issues

1. Duplicate Description in guard.mdx (line 20-21)

The description is duplicated - it appears both in the frontmatter and as a standalone line before the APIPage component. Recommendation: Remove the duplicate description on line 20.

2. Similar Duplication in redact.mdx (line 19-20)

Same issue - the description appears to be duplicated.

3. Schema Requirement Inconsistency

In the multipart/form-data schema (docs/openapi.json:265-266), text is marked as required, but the description says can be empty string when file is provided. This creates an ambiguous API contract.

Recommendation: Change to empty required array and document that at least one of text or file must be provided.

4. Missing File Size/Type Validation Documentation

The error example shows file must be PDF, but the schema does not specify:

• Maximum file size
• Supported PDF versions
• Behavior with encrypted/password-protected PDFs

Performance Considerations

File Upload Implications:

• PDF files can be large, but there is no documented size limit
• Recommend adding maxLength constraint to schema
• Document expected response times for file uploads vs. text
• Consider rate limiting guidance for file uploads

Content-Type Handling: The multipart implementation looks correct - both SDKs properly let the browser/fetch set the boundary parameter.

Security Concerns

File Upload Security

Good defensive practices observed:

• File type validation exists (PDF only)
• Both SDKs implement proper multipart handling
• Error messages appropriately validate file types

Minor Concerns:

• No mention of malicious PDF scanning
• File size limits (potential DoS vector)
• Virus/malware scanning

Recommendation: Ensure the backend validates PDF structure, enforces reasonable file size limits (less than 10MB recommended), and sanitizes file content.

API Key Exposure

Both SDKs correctly handle API keys through headers, not query params - good practice.

Test Coverage

Current State

Strengths:

• TypeScript SDK has comprehensive tests (sdk/typescript/tests/guard.test.ts:10-45)
• Python SDK has similar coverage (sdk/python/tests/test_guard.py:17-62)
• Both SDKs already support File/Blob inputs in the implementation

Gap Identified: No tests for PDF file uploads to the guard endpoint

Both test suites test text input, callbacks, and error handling, but NOT file upload functionality or multipart form-data submission.

Recommendation: Add test cases for file upload scenarios in both SDKs.

Summary and Action Items

Must Fix:

1. Remove duplicate descriptions in guard.mdx and redact.mdx
2. Clarify required fields in multipart schema - current config is ambiguous

Should Add:

3. Document file size limits and PDF requirements
4. Add test coverage for file upload scenarios (both SDKs)
5. Add API reference examples showing file upload usage

Nice to Have:

6. Add OpenAPI examples for multipart requests
7. Document performance characteristics (file vs. text)

Overall Assessment

Rating: Approve with Minor Changes

This is a solid documentation update that aligns the API spec with existing SDK implementations. The core changes are correct and follow good practices. The issues identified are minor and mostly around documentation completeness, test coverage gaps, and minor formatting issues.

The security model is sound, and the implementation in the SDKs is already production-ready. Once the documentation duplicates are removed and test coverage is added, this will be in excellent shape.

Great work on maintaining consistency between the SDK implementations and API documentation!

Files Reviewed:

• docs/openapi.json (+29, -3)
• docs/content/docs/rest-api/guard.mdx (+4, -1)
• docs/content/docs/rest-api/redact.mdx (+2, -0)
• sdk/typescript/src/index.ts (context)
• sdk/python/src/superagent_ai/client.py (context)
• Test files (both SDKs)