docs: refine platform api preview

docs/docs.json

@@ -567,6 +567,16 @@
                       "source": "/edge/openapi/platform-v1.yaml",
                       "directory": "edge/api/v1/platform-api/reference"
                     }
+                  },
+                  {
+                    "group": "Problems",
+                    "pages": [
+                      "edge/api/v1/problems",
+                      "edge/api/v1/problems/bad_request",
+                      "edge/api/v1/problems/not_found",
+                      "edge/api/v1/problems/validation_error",
+                      "edge/api/v1/problems/internal_error"
+                    ]
                   }
                 ]
               },
@@ -1110,6 +1120,16 @@
                       "source": "/v1.14.7/openapi/platform-v1.yaml",
                       "directory": "v1.14.7/api/v1/platform-api/reference"
                     }
+                  },
+                  {
+                    "group": "Problems",
+                    "pages": [
+                      "v1.14.7/api/v1/problems",
+                      "v1.14.7/api/v1/problems/bad_request",
+                      "v1.14.7/api/v1/problems/not_found",
+                      "v1.14.7/api/v1/problems/validation_error",
+                      "v1.14.7/api/v1/problems/internal_error"
+                    ]
                   }
                 ]
               },

docs/edge/api/v1/platform-api/introduction.mdx

@@ -1,17 +1,19 @@
 ---
 title: "Platform API"
-description: "Reference for the CrewAI Platform public API."
+description: "Build against the supported CrewAI Platform public API."
 icon: "code"
 mode: "wide"
 ---
 
 # CrewAI Platform API
 
-The Platform API is the supported public API for interacting with CrewAI
-Platform resources.
+The Platform API is the supported public API for CrewAI Platform. Use it when
+you need stable HTTP contracts for automation, integrations, and agent-facing
+workflows.
 
-This page is authored in `crewai-plus` and copied into the docs repo with the
-generated OpenAPI bundle.
+The current public contract is `v1`. Endpoints live under `/api/v1` on the
+CrewAI Platform app host:
 
-The generated OpenAPI bundle owns endpoint reference details. Authored pages own
-API material that OpenAPI does not model well, such as problem descriptions.
+```text
+https://app.crewai.com/api/v1
+```

docs/edge/api/v1/problems.mdx

@@ -0,0 +1,13 @@
+---
+title: "Problems"
+description: "Error responses returned by the CrewAI Platform API."
+---
+
+# Problems
+
+When a request fails, the Platform API returns an `errors` array. Each item
+includes a stable `code`, an HTTP `status`, and a `detail` message with
+request-specific context.
+
+Use the pages in this section to understand what each error code means and what
+to change before retrying.

docs/edge/openapi/platform-v1.yaml

@@ -4,8 +4,8 @@ info:
   version: v1
   description: Supported public API for CrewAI Platform.
 servers:
-  - url: /
-    description: Current CrewAI Platform host
+  - url: https://app.crewai.com
+    description: CrewAI Platform
 security: []
 tags:
   - name: Status

docs/v1.14.7/api/v1/platform-api/introduction.mdx

@@ -1,17 +1,19 @@
 ---
 title: "Platform API"
-description: "Reference for the CrewAI Platform public API."
+description: "Build against the supported CrewAI Platform public API."
 icon: "code"
 mode: "wide"
 ---
 
 # CrewAI Platform API
 
-The Platform API is the supported public API for interacting with CrewAI
-Platform resources.
+The Platform API is the supported public API for CrewAI Platform. Use it when
+you need stable HTTP contracts for automation, integrations, and agent-facing
+workflows.
 
-This page is authored in `crewai-plus` and copied into the docs repo with the
-generated OpenAPI bundle.
+The current public contract is `v1`. Endpoints live under `/api/v1` on the
+CrewAI Platform app host:
 
-The generated OpenAPI bundle owns endpoint reference details. Authored pages own
-API material that OpenAPI does not model well, such as problem descriptions.
+```text
+https://app.crewai.com/api/v1
+```

docs/v1.14.7/api/v1/problems.mdx

@@ -0,0 +1,13 @@
+---
+title: "Problems"
+description: "Error responses returned by the CrewAI Platform API."
+---
+
+# Problems
+
+When a request fails, the Platform API returns an `errors` array. Each item
+includes a stable `code`, an HTTP `status`, and a `detail` message with
+request-specific context.
+
+Use the pages in this section to understand what each error code means and what
+to change before retrying.

docs/v1.14.7/openapi/platform-v1.yaml

@@ -4,8 +4,8 @@ info:
   version: v1
   description: Supported public API for CrewAI Platform.
 servers:
-  - url: /
-    description: Current CrewAI Platform host
+  - url: https://app.crewai.com
+    description: CrewAI Platform
 security: []
 tags:
   - name: Status