Update API documentation with corrected request/response structure

[lukasmartinelli]

Summary

This PR updates the quickstart guide and API documentation to reflect the correct request and response structure for the Place Enrichment API, with place_id as a top-level field rather than nested within inputs.

Key Changes

• Request Structure: Moved place_id from inside the inputs object to the top level of the request payload across all code examples (cURL, Python, JavaScript)
• Documentation Clarity: Updated the tip section to explicitly state that place_id is required at the top level, not inside inputs
• Input Flexibility Examples: Corrected all three option examples to show the proper nested structure with place_id at top level and input fields within the inputs object
• Response Structure: Updated the example response to include:
  • Top-level status and inputs fields
  • Corrected output field names (websites, phoneNumbers, openingHours, closed_permanently)
  • Added last_enriched timestamp in job_metadata
  • Updated attribute_status to reflect current field names
• API Reference: Updated the attributes table with:
  • Clarified descriptions (e.g., "URLs" instead of "URL", "Phone numbers" instead of "Phone number")
  • Renamed social_profiles to socialHandles
  • Updated categories description to be more generic
• Documentation Configuration: Added redirect rules in docs.json for legacy URLs (/quickstart, /introduction → /guides/quickstart, and /guides/troubleshooting → /guides/troubleshooting-40x)
• OpenAPI Schema: Updated the OpenAPI specification to reflect the corrected API structure

Implementation Details

All examples now consistently demonstrate the correct API contract with place_id as a required top-level field, making the documentation more accurate and reducing developer confusion during integration.

https://claude.ai/code/session_01VTZqLservL8nZ21KUgvnUB

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
syncupai	🟢 Ready	View Preview	Mar 26, 2026, 1:26 AM

[claude]

Claude finished @lukasmartinelli's task —— View job

---

Documentation PR Review

Todo List

• Read changed files to understand modifications
• Extract and test curl examples ⏭️ (Skipped - requires command approval)
• Extract and test Python examples ⏭️ (Skipped - requires command approval)
• Review documentation quality for AI slop
• Provide final assessment

Code Examples Review

Curl Example Analysis:

• ✅ Correct structure with place_id at top level
• ✅ Proper use of {org_slug} and {YOUR_API_KEY} placeholders
• ✅ Valid JSON structure in request body
• ⏭️ Unable to test execution due to command approval requirements

Python Example Analysis:

• ✅ Follows same correct structure as curl
• ✅ Proper error handling and timeout
• ✅ Uses environment variables correctly
• ⏭️ Unable to test execution due to command approval requirements

JavaScript Example Analysis:

• ✅ Uses async/await pattern correctly
• ✅ Same correct API structure
• ⏭️ Skipped as specified for async functions

Documentation Quality Assessment

✅ Positive Changes:

• Clear, concise explanations without unnecessary verbosity
• Good technical precision in API structure documentation
• Helpful tip callout about place_id placement
• Input flexibility examples are practical and well-structured
• Response example matches described API contract
• Redirect rules properly added for legacy URLs

✅ Writing Quality:

• Direct, technical language without AI slop
• No obvious explanations or filler phrases
• Information density is appropriate
• Examples are practical and actionable

✅ API Correctness:

• Request structure correctly shows place_id at top level
• Response example includes all documented fields (status, inputs, outputs, job_metadata)
• Attribute names match current API (websites, phoneNumbers, openingHours)
• Updated attributes table with better descriptions

Minor Observations:

• Apostrophe handling in curl example could be cleaner (Joe'\''s vs Joes)
• Consistent naming between curl (Joe's Pizza) and other examples (Joes Pizza)

Assessment: DEFINITELY_FINE

The documentation changes correctly implement the API structure with place_id at the top level, examples appear syntactically correct, and the writing quality is high without AI slop. The changes align with good technical documentation practices.

[claude]

Claude finished @lukasmartinelli's task —— View job

---

Documentation PR Review

Todo List

• Read changed files to understand modifications
• Extract and test curl examples
• Extract and test Python examples
• Review documentation quality for AI slop
• Provide final assessment

Code Example Analysis

Curl Example (lines 23-38):
⏭️ SKIP - Cannot execute due to tool restrictions, but structure looks correct:

• ✅ place_id correctly moved to top level
• ✅ inputs object properly structured
• ✅ Environment variable placeholders {YOUR_API_KEY} and {org_slug} present

Python Example (lines 40-63):
⏭️ SKIP - Cannot execute due to tool restrictions, but structure looks correct:

• ✅ place_id at top level in data dict
• ✅ inputs nested correctly
• ✅ Environment variable placeholders present
• ✅ Standard requests.post() usage

JavaScript Example (lines 65-86):
⏭️ SKIP - Cannot execute due to tool restrictions, but structure looks correct:

• ✅ place_id at top level in JSON body
• ✅ inputs nested correctly
• ✅ Standard fetch() API usage

Input Flexibility Examples (lines 101-134):
✅ PASS - All three JSON examples show correct structure:

• place_id at top level ✓
• inputs as nested object ✓
• Consistent formatting ✓

Documentation Quality Assessment

✅ NO AI SLOP DETECTED - Content is concise and technical:

• Direct, actionable instructions
• No verbose explanations or filler phrases
• Good use of structured examples
• Clear section organization
• Appropriate use of tips/notes without over-explaining

Key Improvements Identified:

• Response example (lines 144-173) shows realistic API structure
• Tip section (lines 92-94) clearly explains place_id requirement
• Redirects in docs.json maintain backward compatibility

Final Assessment: PROBABLY_FINE

Reasoning: All code examples show correct API structure with place_id at top level. Cannot execute examples due to tool restrictions, but manual review shows proper request format, environment variable usage, and response structure. Documentation is well-written without AI slop. The changes correctly address the API structure issue described in the PR.

Recommendation: Approve after confirming examples work in actual testing environment.