chore: improved docs for document/by-id endpoint, added a couple of warnings based on mintlify questions

[naman06dev]

[graphite-app]

How to use the Graphite Merge Queue

Add the label Main to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

[claude]

Pull Request Review: Documentation Improvements for Document Retrieval

Summary

This PR adds valuable clarifications about document retrieval endpoints and the customId field length limitation. The additions improve developer experience by providing better guidance on when to use direct retrieval vs. semantic search.

Strengths

1. Clear Use Case Differentiation (search/overview.mdx:288-328)

   • Excellent addition explaining when to use GET /v3/documents/{id} vs. semantic search
   • Helpful when to use list makes the decision clear for developers
   • Good cross-references to API documentation

2. Comprehensive Code Examples

   • Includes TypeScript, Python, and cURL examples consistently
   • Shows practical usage with relevant fields (content, status, metadata, summary)

3. Important Constraint Documentation (update-delete-memories/overview.mdx:154-158)

   • Critical addition: customId max length of 100 characters
   • Properly formatted as a Warning block for visibility

4. Helpful Cross-Reference (memory-api/track-progress.mdx:157)

   • Links to comprehensive API reference for additional details

Observations and Suggestions

1. Documentation Consistency

The new Direct Document Retrieval section appears in search/overview.mdx, but this file already has a section about individual document tracking at line 100-156. Consider whether these sections overlap in purpose and if they should be consolidated or clearly differentiated.

2. Content Accuracy Check

Please verify that the summary field is always present in the response (or document when it is available) and that the field name matches the actual API response.

3. Link Validation

The PR references /api-reference/manage-documents/get-document. Since the API Reference is generated from the OpenAPI spec, please verify this path will be generated correctly.

4. customId Length Constraint Context

The warning about 100 character limit is excellent. Consider also mentioning what happens if you exceed 100 characters and best practices for choosing customId values.

Recommendation

Approve with minor verification

This PR significantly improves the documentation quality. Before merging, please verify the API reference link path is correct, the summary field example matches actual API responses, and the document flow reads naturally.

Great work improving the developer experience!

[claude]

Pull Request Review - PR #550

Overview

This PR adds helpful documentation improvements for the document retrieval endpoint and clarifies the customId field constraints. The changes enhance user experience by providing clearer guidance on when to use direct document retrieval vs semantic search.

---

Code Quality & Best Practices ✅

Positive aspects:

• Clear, well-structured documentation additions
• Good use of code examples across multiple languages (TypeScript, Python, cURL)
• Proper use of Mintlify components (<Note>, <Warning>, <CodeGroup>)
• Contextual placement of information where users need it most

Suggestions:

1. Consistency needed: The customId max length is documented as 255 characters in /apps/docs/memory-api/ingesting.mdx:154, but your new warning states 100 characters. Please verify the actual constraint in the database schema/validation layer and ensure consistency across all documentation.

2. Cross-reference improvement: Consider adding a similar note about the customId length constraint in the ingesting.mdx file where it's first introduced (line 154), not just in the update/delete section.

---

Content & Clarity ✅

"Direct Document Retrieval" section (search/overview.mdx):

• Excellent addition! This clarifies when to use GET vs search endpoints
• The "This is useful when" bulleted list provides clear decision criteria
• Code examples are comprehensive and practical

Track Progress improvements (memory-api/track-progress.mdx):

• Good addition of the API reference link for more details
• Helps users discover the full API documentation

customId Warning (update-delete-memories/overview.mdx):

• Important constraint to highlight
• However, needs verification (see discrepancy noted above)

---

Potential Issues ⚠️

Critical - Documentation Inconsistency:

• Location 1: apps/docs/memory-api/ingesting.mdx:154 states: "max 255 characters"
• Location 2: Your new addition states: "max 100 characters"

Action needed:

1. Check the actual database schema or validation rules (likely in packages/validation or database migrations)
2. Update all documentation to reflect the correct constraint
3. If the constraint changed from 255→100, consider if this is a breaking change that needs migration guidance

---

Performance Considerations ✅

No performance concerns - documentation only changes.

---

Security Concerns ✅

No security issues identified. The documentation appropriately uses placeholder values and doesn't expose sensitive information.

---

Test Coverage

Not applicable - documentation changes don't require tests. However, consider:

• Testing the code examples to ensure they're accurate
• Verifying the example document IDs follow the correct format

---

Recommendations

Before merging:

1. Resolve the customId length discrepancy - this is critical for API consumers
2. Consider adding the customId length constraint note to the ingesting.mdx file as well
3. Verify all code examples are tested and work correctly

Nice to have:

• Add a note about what happens if users exceed the customId length (validation error response)
• Consider linking to the error handling documentation

---

Summary

Overall, this is a valuable documentation improvement that addresses user questions from Mintlify. The content is well-written and properly structured. The main blocker is resolving the customId length inconsistency before merging.

Status: Requires changes - Please address the customId length discrepancy, then this should be good to merge! 👍

[claude]

Pull Request Review

Thank you for improving the documentation! This PR adds helpful clarifications for the document/by-id endpoint. Here's my detailed feedback:

✅ Strengths

1. Improved Navigation: Adding the cross-reference link to the API reference in track-progress.mdx is helpful for users who need more comprehensive information.

2. Better User Guidance: The "Direct Document Retrieval" section in search/overview.mdx provides clear guidance on when to use direct retrieval vs. semantic search.

3. Important Constraint Documentation: The customId length limit warning is valuable information that should be documented.

🐛 Issues Found

1. Inconsistent Placeholder Usage (apps/docs/search/overview.mdx:336)

curl -X GET "https://api.supermemory.ai/v3/documents/{YOUR-DOCUMENT-ID}" \

Issue: Uses {YOUR-DOCUMENT-ID} format while the rest of the codebase uses consistent doc_abc123 style examples.

Recommendation: Use a consistent example ID like doc_abc123 to match the patterns in track-progress.mdx:134.

2. Redundant Information (apps/docs/search/overview.mdx:288-327)

The new "Direct Document Retrieval" section duplicates content already covered in track-progress.mdx (lines 100-155).

Recommendation:

• Keep the brief explanation and use case bullets
• Replace the full code examples with a concise note directing users to the track-progress page
• Example: "For detailed examples and tracking document processing status, see Track Processing Status"

3. Missing Context in Note (apps/docs/search/overview.mdx:323-325)

The Note mentions "complete document with all fields" but doesn't explain what users get vs. search results.

Recommendation: Clarify the difference:

<Note>
This endpoint returns the complete document with all fields including content, metadata, containerTags, summary, and processing status—unlike search endpoints which return only matching chunks. For more details and processing status tracking, see the [API reference](/api-reference/manage-documents/get-document) and [Track Processing Status](/memory-api/track-progress).
</Note>

📝 Style & Conventions

Based on the repository's documentation patterns:

1. Code Example Consistency: The codebase uses doc_abc123, mem_xyz789 style IDs consistently. The new {YOUR-DOCUMENT-ID} breaks this pattern.

2. DRY Principle: The documentation has existing comprehensive examples for the GET document endpoint. The new section should reference rather than duplicate.

🎯 Suggestions for Improvement

1. Simplify the new section to focus on the use case explanation and when to use it, then link to the comprehensive guide.

2. Keep the customId warning - this is valuable new information.

3. Keep the cross-reference link in track-progress.mdx - this improves navigation.

🔒 Security & Performance

No security concerns or performance issues identified. This is purely documentation.

✅ Test Coverage

Documentation changes don't require tests, but consider:

• Verifying all links work correctly
• Ensuring code examples are valid and tested against the actual API

Summary

This PR addresses real user needs based on Mintlify questions, which is excellent. The main improvements needed are:

1. Reduce duplication by linking to existing comprehensive examples
2. Maintain consistency in example IDs and patterns
3. Clarify the differences between endpoints more explicitly

Would you like me to suggest specific edits to address these points?

[claude]

PR Review: Documentation Improvements for document/by-id endpoint

✅ Positive Aspects

1. Excellent Documentation Enhancements

• Added helpful cross-reference to API reference in track-progress.mdx:157 - improves discoverability
• New "Direct Document Retrieval" section in search/overview.mdx:288-327 provides clear guidance on when to use GET vs search
• Code examples across TypeScript, Python, and cURL are comprehensive and well-formatted

2. Important User Guidance

• The distinction between semantic search and direct retrieval is valuable for API users
• Clear use cases help developers choose the right endpoint
• Added character limit warning for customId (100 chars) prevents API errors

3. Code Quality

• Follows existing documentation patterns and structure
• Proper use of MDX components (<CodeGroup>, <Note>, <Warning>)
• Consistent formatting with repository standards

📝 Suggestions for Improvement

1. Minor Documentation Consistency

In search/overview.mdx:298, the TypeScript example accesses fields like document.summary and document.status, but it would be helpful to mention that some fields may be null depending on processing status:

// Consider adding a note about nullable fields
console.log(document.summary);    // AI-generated summary (may be null if processing)
console.log(document.status);     // Processing status: 'pending' | 'completed' | 'failed'

2. Error Handling Examples

Consider adding a brief note about error cases (e.g., document not found, invalid ID format):

try {
  const document = await client.memories.get("doc_abc123");
} catch (error) {
  // Handle 404 if document doesn't exist
}

3. CustomId Warning Placement

The customId character limit warning in update-delete-memories/overview.mdx:154-157 is great! Consider also mentioning:

• Allowed characters (alphanumeric, hyphens, underscores?)
• Case sensitivity
• Whether special characters are permitted

🔍 Technical Considerations

No Security Concerns: Documentation changes only, no code execution paths affected.

No Performance Impact: Static documentation content.

No Breaking Changes: Purely additive documentation improvements.

📊 Test Coverage

N/A - Documentation changes don't require automated tests, but the code examples should be manually verified to ensure they work as documented.

✅ Final Recommendation

APPROVE - This PR makes meaningful improvements to the documentation that will help users better understand:

1. When to use direct document retrieval vs semantic search
2. The character limits and constraints on customId
3. How to access document details across different SDK languages

The changes align well with the repository's documentation standards and address real user questions (as mentioned in the PR title "based on mintlify questions").

Minor optional enhancements suggested above would add even more value, but the PR is ready to merge as-is.

---

Great work @naman06dev on improving the developer experience! 🎉

[graphite-app]