diff --git a/docs/docs.json b/docs/docs.json index 4b49fae7c..ee4ca027e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -551,6 +551,19 @@ } ] }, + { + "tab": "Platform API", + "icon": "code", + "groups": [ + { + "group": "Reference", + "openapi": "/openapi/platform-v1.yaml", + "pages": [ + "edge/api/v1/platform-api/introduction" + ] + } + ] + }, { "tab": "Examples", "icon": "code", diff --git a/docs/edge/api/v1/platform-api/introduction.mdx b/docs/edge/api/v1/platform-api/introduction.mdx new file mode 100644 index 000000000..c4fac4fbd --- /dev/null +++ b/docs/edge/api/v1/platform-api/introduction.mdx @@ -0,0 +1,17 @@ +--- +title: "Platform API" +description: "Reference for the 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. + +This page is authored in `crewai-plus` and copied into the docs repo with the +generated OpenAPI bundle. + +The generated OpenAPI bundle owns endpoint reference details. Authored pages own +API material that OpenAPI does not model well, such as problem descriptions. diff --git a/docs/edge/api/v1/problems/bad_request.mdx b/docs/edge/api/v1/problems/bad_request.mdx new file mode 100644 index 000000000..646d890a8 --- /dev/null +++ b/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. diff --git a/docs/edge/api/v1/problems/internal_error.mdx b/docs/edge/api/v1/problems/internal_error.mdx new file mode 100644 index 000000000..9c65569b5 --- /dev/null +++ b/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. diff --git a/docs/edge/api/v1/problems/not_found.mdx b/docs/edge/api/v1/problems/not_found.mdx new file mode 100644 index 000000000..22a435a2d --- /dev/null +++ b/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. diff --git a/docs/edge/api/v1/problems/validation_error.mdx b/docs/edge/api/v1/problems/validation_error.mdx new file mode 100644 index 000000000..1db560ffe --- /dev/null +++ b/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. diff --git a/docs/edge/openapi/platform-v1.yaml b/docs/edge/openapi/platform-v1.yaml new file mode 100644 index 000000000..b9e9f0757 --- /dev/null +++ b/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: / + description: Current CrewAI Platform host +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.