DR-6257 Management API Docs Updates

[aidankmcalister]

Summary by CodeRabbit

• Documentation
  • Enhanced API docs for project creation: added detailed response examples including workspace, database, and direct connection credentials, plus guidance and an example for constructing a DATABASE_URL and environment variable snippet.
  • Added a new Databases usage endpoint (GET /databases/{databaseId}/usage) with date-range query support, full response schema, and documented HTTP status codes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[github-actions]

Dangerous URL check

No absolute URLs to prisma.io/docs found.
No local URLs found.

[github-actions]

original	preview
content/250-postgres/100-introduction/230-management-api.mdx	content/250-postgres/100-introduction/230-management-api.mdx

[github-actions]

Redirect check

This PR probably requires the following redirects to be added to static/_redirects:

• This PR does not change any pages in a way that would require a redirect.

[coderabbitai]

Walkthrough

Added detailed response examples and environment guidance to the POST /projects documentation and introduced a new GET /databases/{databaseId}/usage endpoint with query parameters, full response schema, and status code documentation.

Changes

Cohort / File(s)

Summary

API docs (single file) content/250-postgres/100-introduction/230-management-api.mdx

Added a detailed POST /projects response example including nested project, workspace, and database objects with a directConnection credentials block and guidance/example for constructing DATABASE_URL; added a new GET /databases/{databaseId}/usage endpoint with startDate/endDate query parameters, full JSON response schema (period, metrics, generatedAt), and documented responses (200, 400, 401, 404, 500).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify the GET /databases/{databaseId}/usage parameter names, date format expectations, and status codes match the actual API implementation.
• Confirm directConnection credential field names and types correspond to the backend response.
• Validate the DATABASE_URL construction example (escaping, encoding, and port/database name placement) to avoid connection issues.

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'DR-6257 Management API Docs Updates' directly relates to the changeset, which documents new API endpoints and response structures for the Management API.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a749af6 and f1cba2e.

📒 Files selected for processing (1)

• content/250-postgres/100-introduction/230-management-api.mdx (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Check internal links
• GitHub Check: Cloudflare Pages

🔇 Additional comments (1)

content/250-postgres/100-introduction/230-management-api.mdx (1)

370-405: Well-documented new endpoint.

The GET /databases/{databaseId}/usage documentation is clear and comprehensive—good coverage of path parameters, optional query parameters, complete response schema with realistic example values, and appropriate HTTP status codes.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	f1cba2e
Status:	✅  Deploy successful!
Preview URL:	https://577f0a1d.docs-51g.pages.dev
Branch Preview URL:	https://dr-6257-management-api-docs.docs-51g.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

content/250-postgres/100-introduction/230-management-api.mdx (1)

370-405: Specify startDate/endDate format + semantics (timezone, inclusivity, defaults, validation rules)

The endpoint is clear, but readers will get stuck on what values are accepted/expected for startDate and endDate (ISO-8601? date-only vs timestamp? UTC required? inclusive/exclusive? what happens if omitted? max range?).

A small doc add would prevent 400s and support tickets—for example:

• startDate, endDate: ISO 8601 timestamps (UTC recommended), e.g. 2025-12-01T00:00:00.000Z
• If omitted: default period (e.g., “last 30 days”) — whatever the API does
• Validation: startDate <= endDate, max period length, and whether future dates are allowed

If the OpenAPI spec already defines this, mirror it here verbatim to keep the guide aligned.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 980e2ec and a749af6.

📒 Files selected for processing (1)

• content/250-postgres/100-introduction/230-management-api.mdx (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Check internal links
• GitHub Check: Cloudflare Pages