docs: refine platform api preview

docs/docs.json

@@ -551,6 +551,35 @@
                   }
                 ]
               },
+              {
+                "tab": "Platform API",
+                "icon": "code",
+                "groups": [
+                  {
+                    "group": "Overview",
+                    "pages": [
+                      "edge/api/v1/platform-api/introduction"
+                    ]
+                  },
+                  {
+                    "group": "Reference",
+                    "openapi": {
+                      "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"
+                    ]
+                  }
+                ]
+              },
               {
                 "tab": "Examples",
                 "icon": "code",
@@ -1075,6 +1104,35 @@
                   }
                 ]
               },
+              {
+                "tab": "Platform API",
+                "icon": "code",
+                "groups": [
+                  {
+                    "group": "Overview",
+                    "pages": [
+                      "v1.14.7/api/v1/platform-api/introduction"
+                    ]
+                  },
+                  {
+                    "group": "Reference",
+                    "openapi": {
+                      "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"
+                    ]
+                  }
+                ]
+              },
               {
                 "tab": "Examples",
                 "icon": "code",

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

@@ -0,0 +1,19 @@
+---
+title: "Platform 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 CrewAI Platform. Use it when
+you need stable HTTP contracts for automation, integrations, and agent-facing
+workflows.
+
+The current public contract is `v1`. Endpoints live under `/api/v1` on the
+CrewAI Platform app host:
+
+```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/api/v1/problems/bad_request.mdx

@@ -0,0 +1,17 @@
+---
+code: bad_request
+title: Bad request
+status: 400
+---
+
+# Bad request
+
+The request could not be processed because it was malformed or missing required request data.
+
+## When It Happens
+
+This usually means the request body, query string, headers, or required parameters are invalid before endpoint-specific validation can run.
+
+## How To Fix
+
+Review the endpoint contract, required parameters, request body shape, and content type before retrying.

docs/edge/api/v1/problems/internal_error.mdx

@@ -0,0 +1,17 @@
+---
+code: internal_error
+title: Internal error
+status: 500
+---
+
+# Internal error
+
+An unexpected server-side failure prevented the request from completing.
+
+## When It Happens
+
+This means the platform encountered an unexpected condition while processing a valid request.
+
+## How To Fix
+
+Retry the request after a short delay. If the problem continues, contact support with the request details and timestamp.

docs/edge/api/v1/problems/not_found.mdx

@@ -0,0 +1,17 @@
+---
+code: not_found
+title: Not found
+status: 404
+---
+
+# Not found
+
+The requested resource does not exist or is not available at the requested path.
+
+## When It Happens
+
+This can happen when the URL is incorrect, the resource identifier does not exist, or the resource is not visible through the public API.
+
+## How To Fix
+
+Check the endpoint path and resource identifier, then retry with a resource that exists and is available to the request.

docs/edge/api/v1/problems/validation_error.mdx

@@ -0,0 +1,17 @@
+---
+code: validation_error
+title: Validation error
+status: 422
+---
+
+# Validation error
+
+The request was understood, but one or more submitted values failed validation.
+
+## When It Happens
+
+This usually means a submitted field is missing, malformed, out of range, duplicated, or conflicts with another value.
+
+## How To Fix
+
+Inspect the `detail` message for the field-specific issue, update the submitted values, and retry the request.

docs/edge/openapi/platform-v1.yaml

@@ -0,0 +1,115 @@
+openapi: 3.0.1
+info:
+  title: CrewAI Platform API
+  version: v1
+  description: Supported public API for CrewAI Platform.
+servers:
+  - url: https://app.crewai.com
+    description: CrewAI Platform
+security: []
+tags:
+  - name: Status
+    description: Platform health and API availability.
+paths:
+  /api/v1/status:
+    get:
+      summary: Check API status
+      operationId: getStatus
+      tags:
+        - Status
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              examples:
+                success:
+                  value:
+                    data:
+                      status: ok
+                  summary: API is available
+              schema:
+                type: object
+                required:
+                  - data
+                additionalProperties: false
+                properties:
+                  data:
+                    type: object
+                    required:
+                      - status
+                    additionalProperties: false
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        example: ok
+components:
+  schemas:
+    SuccessEnvelope:
+      type: object
+      required:
+        - data
+      additionalProperties: false
+      properties:
+        data:
+          description: Endpoint-specific response payload.
+    ErrorEnvelope:
+      type: object
+      required:
+        - errors
+      additionalProperties: false
+      properties:
+        errors:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/Error'
+    Error:
+      type: object
+      description: Public API error object.
+      required:
+        - type
+        - code
+        - title
+        - status
+        - detail
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          format: uri
+          enum:
+            - https://docs.crewai.com/api/v1/problems/bad_request
+            - https://docs.crewai.com/api/v1/problems/internal_error
+            - https://docs.crewai.com/api/v1/problems/not_found
+            - https://docs.crewai.com/api/v1/problems/validation_error
+          example: https://docs.crewai.com/api/v1/problems/bad_request
+        code:
+          type: string
+          enum:
+            - bad_request
+            - internal_error
+            - not_found
+            - validation_error
+          example: bad_request
+        title:
+          type: string
+          enum:
+            - Bad request
+            - Internal error
+            - Not found
+            - Validation error
+          example: Bad request
+        status:
+          type: integer
+          enum:
+            - 400
+            - 404
+            - 422
+            - 500
+          example: 400
+        detail:
+          type: string
+          example: The request is invalid.

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

@@ -0,0 +1,19 @@
+---
+title: "Platform 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 CrewAI Platform. Use it when
+you need stable HTTP contracts for automation, integrations, and agent-facing
+workflows.
+
+The current public contract is `v1`. Endpoints live under `/api/v1` on the
+CrewAI Platform app host:
+
+```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/api/v1/problems/bad_request.mdx

@@ -0,0 +1,17 @@
+---
+code: bad_request
+title: Bad request
+status: 400
+---
+
+# Bad request
+
+The request could not be processed because it was malformed or missing required request data.
+
+## When It Happens
+
+This usually means the request body, query string, headers, or required parameters are invalid before endpoint-specific validation can run.
+
+## How To Fix
+
+Review the endpoint contract, required parameters, request body shape, and content type before retrying.

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

@@ -0,0 +1,17 @@
+---
+code: internal_error
+title: Internal error
+status: 500
+---
+
+# Internal error
+
+An unexpected server-side failure prevented the request from completing.
+
+## When It Happens
+
+This means the platform encountered an unexpected condition while processing a valid request.
+
+## How To Fix
+
+Retry the request after a short delay. If the problem continues, contact support with the request details and timestamp.

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

@@ -0,0 +1,17 @@
+---
+code: not_found
+title: Not found
+status: 404
+---
+
+# Not found
+
+The requested resource does not exist or is not available at the requested path.
+
+## When It Happens
+
+This can happen when the URL is incorrect, the resource identifier does not exist, or the resource is not visible through the public API.
+
+## How To Fix
+
+Check the endpoint path and resource identifier, then retry with a resource that exists and is available to the request.

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

@@ -0,0 +1,17 @@
+---
+code: validation_error
+title: Validation error
+status: 422
+---
+
+# Validation error
+
+The request was understood, but one or more submitted values failed validation.
+
+## When It Happens
+
+This usually means a submitted field is missing, malformed, out of range, duplicated, or conflicts with another value.
+
+## How To Fix
+
+Inspect the `detail` message for the field-specific issue, update the submitted values, and retry the request.

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

@@ -0,0 +1,115 @@
+openapi: 3.0.1
+info:
+  title: CrewAI Platform API
+  version: v1
+  description: Supported public API for CrewAI Platform.
+servers:
+  - url: https://app.crewai.com
+    description: CrewAI Platform
+security: []
+tags:
+  - name: Status
+    description: Platform health and API availability.
+paths:
+  /api/v1/status:
+    get:
+      summary: Check API status
+      operationId: getStatus
+      tags:
+        - Status
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              examples:
+                success:
+                  value:
+                    data:
+                      status: ok
+                  summary: API is available
+              schema:
+                type: object
+                required:
+                  - data
+                additionalProperties: false
+                properties:
+                  data:
+                    type: object
+                    required:
+                      - status
+                    additionalProperties: false
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        example: ok
+components:
+  schemas:
+    SuccessEnvelope:
+      type: object
+      required:
+        - data
+      additionalProperties: false
+      properties:
+        data:
+          description: Endpoint-specific response payload.
+    ErrorEnvelope:
+      type: object
+      required:
+        - errors
+      additionalProperties: false
+      properties:
+        errors:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/Error'
+    Error:
+      type: object
+      description: Public API error object.
+      required:
+        - type
+        - code
+        - title
+        - status
+        - detail
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          format: uri
+          enum:
+            - https://docs.crewai.com/api/v1/problems/bad_request
+            - https://docs.crewai.com/api/v1/problems/internal_error
+            - https://docs.crewai.com/api/v1/problems/not_found
+            - https://docs.crewai.com/api/v1/problems/validation_error
+          example: https://docs.crewai.com/api/v1/problems/bad_request
+        code:
+          type: string
+          enum:
+            - bad_request
+            - internal_error
+            - not_found
+            - validation_error
+          example: bad_request
+        title:
+          type: string
+          enum:
+            - Bad request
+            - Internal error
+            - Not found
+            - Validation error
+          example: Bad request
+        status:
+          type: integer
+          enum:
+            - 400
+            - 404
+            - 422
+            - 500
+          example: 400
+        detail:
+          type: string
+          example: The request is invalid.