Correct Neo API docs

[flostadler]

Proposed changes

The Neo API docs were wrong. This change corrects them

[claude]

Documentation Review

Thank you for correcting the Neo API documentation. This is a substantial improvement with better structure and more accurate API details. I've identified several issues that should be addressed:

---

Issues Found

1. Inconsistent status values (Line 164)

The response field description mentions statuses "running" or "idle", but the old documentation mentioned "pending", "running", "completed", "failed" as possible statuses.

Location: content/docs/reference/cloud-rest-api/neo/_index.md:164

Issue: The new documentation only mentions "running" or "idle". Are the old statuses no longer valid, or is the description incomplete? This needs clarification.

---

2. Optional parameter formatting (Lines 189-190)

The List Tasks endpoint uses "Optional." with bold formatting.

Location: content/docs/reference/cloud-rest-api/neo/_index.md:189-190

Suggestion: Remove the bold formatting from "Optional" to match standard API documentation conventions.

---

3. Response section naming (Lines 86, 139, 203, 272, 306)

The phrase "Default response" appears before each response section.

Suggestion: Consider using "Response" or "Success response" for consistency with common API documentation patterns, unless "Default response" is intentional terminology.

---

4. Table spacing

According to STYLE-GUIDE.md, headings should be surrounded by blank lines. Review sections to ensure consistent blank line spacing around all tables and headings.

---

5. Missing file ending newline

Please ensure the file ends with a newline as required by AGENTS.md.

---

Positive Changes

• Corrected API endpoint URLs to include /api/preview/agents/...
• Added detailed entity type documentation (Stack, Repository, Pull Request, Policy Issue)
• Added user event types documentation (User Message, User Confirmation, User Cancel)
• Improved request/response examples with more realistic data
• Better organization with cross-references to entity types and event types
• Consistent table formatting for parameters
• Added proper HTTP status codes in responses
• Improved curl examples with proper headers
• Better structure with clear sections
• Removed confusing Authentication and Base URL sections from the middle
• Streamlined the introduction

---

Recommendations

1. Clarify task statuses - verify and document all valid values
2. Standardize Optional parameter formatting (remove bold)
3. Verify curl commands are executable as written
4. Review spacing around tables and headings
5. Confirm response section naming preference
6. Add trailing newline

---

Overall, this is a significant improvement to the API documentation. The changes add much-needed detail and correct several structural issues. The addition of Entity Types and User Event Types sections is particularly valuable.

Mention @claude if you'd like me to review the updates or help with any fixes.

[pulumi-bot]

Your site preview for commit e1a6392 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16358-e1a6392d.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit 5260f1d is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16358-5260f1d0.s3-website.us-west-2.amazonaws.com.

[claude]

Review of Neo API Documentation Changes

This PR significantly improves the Neo API documentation by correcting endpoints, restructuring content, and providing better examples. However, there are several issues that need to be addressed before merging.

Critical Issues

1. Missing authentication and base URL information (Lines 16-24)

The authentication and base URL sections were removed entirely. This critical information is necessary for users to successfully make API calls.

Issue: Users will not know how to authenticate their requests or what base URL to use.

Suggestion: Keep the authentication and base URL sections. Consider moving them after the operations list rather than removing them:

## Agent Task Operations

The API provides endpoints for the following operations:

- Creating new agent tasks
- Listing available tasks
- Getting task details and metadata
- Responding to agent requests
- Retrieving task events

## Authentication

All requests must be authenticated using a token via the `Authorization` HTTP header:

```plain
Authorization: token {token}

Base URL

For Managed Pulumi Cloud (app.pulumi.com):

https://api.pulumi.com

For Self-Hosted Pulumi Cloud, use your configured API endpoint.

#### 2. Inconsistent task status values
- Line 162: Lists status as "running" or "idle"
- Line 215: Shows example status as "running"
- Original version mentioned: "pending, running, completed, failed"

**Issue:** The documentation should specify all possible status values consistently.

**Suggestion:** Clarify all possible task status values. If the API changed, document all valid statuses in one place.

#### 3. Incorrect heading level for sub-sections (Line 158)
"Response Fields" uses H4 (####) after a direct H3, creating an inconsistent hierarchy.

**Issue:** Per STYLE-GUIDE.md and AGENTS.md, headings should only increment one level at a time.

**Suggestion:**
```markdown
### Response Fields

Style Issues

4. Missing content for "Respond to Agent Task" endpoint (Line 255)

The request body section says "See the User Event Types section" but does not provide an inline example or summary of the structure.

Issue: Users need to understand the basic request structure before jumping to detailed event type documentation.

Suggestion: Add a basic example showing the structure before referring to the detailed section.

5. Response code formatting inconsistency

Some responses show status codes in plain text blocks (e.g., Lines 88, 134, 198), while the original used inline text.

Issue: While this is acceptable, ensure consistency throughout the document.

6. Task naming in response examples

Line 95: The response shows "taskId": "task_abc123" but Line 150 shows "id": "task_abc123"

Issue: Field naming should be consistent across endpoints.

Clarification needed: Is it taskId in the create response and id in the get response? If so, add a note explaining this difference.

Minor Issues

7. Timestamp format examples

All timestamp examples use "2025-01-15T00:00:00Z" or "2025-01-15T10:30:00Z".

Suggestion: Use consistent, realistic timestamps that show actual time components (e.g., "2025-01-15T14:32:17Z") to better illustrate the ISO 8601 format.

8. Error response details (Lines 107, 174, 229, 278, 354)

Error responses only list status codes without example error bodies.

Suggestion: Add example error response bodies to help developers debug issues more effectively.

9. Authorization section removed (Lines 398-411)

The authorization requirements section was completely removed, including information about required permissions (AgentsReadAuth, AgentsReadWriteAuth).

Issue: This is critical security information that developers need to understand access control.

Suggestion: Restore this section or incorporate permission requirements into each endpoint description.

10. Rate limiting section removed (Lines 413-415)

Rate limiting information was removed entirely.

Issue: Developers need to know about rate limits to implement proper retry logic.

Suggestion: Restore the rate limiting section.

Positive Changes

• ✓ Corrected API endpoint paths from /preview/agents/ to /api/preview/agents/
• ✓ Added comprehensive entity types documentation
• ✓ Added user event types documentation
• ✓ Improved curl examples with proper formatting
• ✓ Better structured parameter tables with "In" column
• ✓ More realistic request/response examples
• ✓ Added status code blocks for better clarity
• ✓ Restructured content with better logical flow

Recommendations

1. Restore authentication and base URL sections (critical for users)
2. Restore authorization and rate limiting sections (important operational information)
3. Clarify task status values throughout the document
4. Fix heading hierarchy issues (H4 should be H3)
5. Add inline request structure examples before referring to detailed sections
6. Verify field naming consistency (taskId vs id)
7. Consider adding error response examples

---

Mention @claude if you would like me to review again after making changes or if you need help implementing any of these suggestions.

[pulumi-bot]

Your site preview for commit 98c5be2 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16358-98c5be25.s3-website.us-west-2.amazonaws.com.

[foot]

Were this auto-gen'd from somewhere?

[flostadler]

Were this auto-gen'd from somewhere?

No, handwritten. Just wrongly, handwritten :(

[pulumi-bot]

Your site preview for commit e0b2f01 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16358-e0b2f01f.s3-website.us-west-2.amazonaws.com.

[foot]

Ah!

I made a weird assumption that neo API docs were published because we auto generated API docs for everything and so it was easier to have neo included here than not. But, cool to have them, and ns'd under /preview/.

[foot]

Looks pretty correct to me! Definitely an improvement