Carlos
- Updated: March 18, 2026
- 7 min read
OpenClaw Plugin Rating API: Updated Full OpenAPI Specification and Multi‑Language SDK Generation Guide
The OpenClaw Plugin Rating API offers a complete OpenAPI (Swagger) definition that lets developers submit, query, and manage plugin ratings, and you can instantly generate ready‑to‑use SDKs for JavaScript, Python, and Go with a few command‑line steps.
Why AI Agents Are Driving a New Wave of Plugin Ecosystems
In 2024 the buzz around AI agents has moved from experimental labs to production‑grade platforms. Companies are building agents that can browse the web, automate workflows, and even rate third‑party extensions on the fly. To keep this momentum, developers need a reliable, language‑agnostic way to expose rating data—enter the OpenClaw Plugin Rating API.
This guide walks you through the full OpenAPI specification, then shows how to spin up SDKs for the three most popular developer stacks. By the end, you’ll be able to integrate rating capabilities into your own AI‑agent products in minutes, not days.
OpenClaw Plugin Rating API – At a Glance
- Purpose: Create, read, update, and delete (CRUD) rating records for plugins hosted on the OpenClaw marketplace.
- Authentication: Bearer token (JWT) passed in the
Authorizationheader. - Rate limits: 120 requests per minute per token.
- Data model: Rating includes
plugin_id,user_id,score(1‑5),comment, and timestamps. - Versioning: v1.0 – stable, with a
/v2preview branch planned for advanced analytics.
Full OpenAPI (Swagger) Specification
Below is the complete OpenAPI 3.0 JSON document. Save it as openclaw-rating-api.json to use with code generators.
{
"openapi": "3.0.3",
"info": {
"title": "OpenClaw Plugin Rating API",
"description": "API for submitting and retrieving plugin ratings on the OpenClaw marketplace.",
"version": "1.0.0",
"contact": {
"name": "OpenClaw Team",
"url": "https://ubos.tech/host-openclaw/",
"email": "support@openclaw.io"
}
},
"servers": [
{
"url": "https://api.openclaw.io/v1",
"description": "Production server"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"schemas": {
"Rating": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-5678-90ab-cdef-1234567890ab" },
"plugin_id": { "type": "string", "example": "plugin-xyz" },
"user_id": { "type": "string", "example": "user-123" },
"score": { "type": "integer", "minimum": 1, "maximum": 5, "example": 4 },
"comment": { "type": "string", "maxLength": 500, "example": "Great integration, very stable." },
"created_at": { "type": "string", "format": "date-time", "example": "2024-03-01T12:34:56Z" },
"updated_at": { "type": "string", "format": "date-time", "example": "2024-03-02T08:15:30Z" }
},
"required": ["plugin_id", "user_id", "score"]
},
"RatingCreate": {
"type": "object",
"properties": {
"plugin_id": { "type": "string", "example": "plugin-xyz" },
"score": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5 },
"comment": { "type": "string", "maxLength": 500, "example": "Excellent plugin!" }
},
"required": ["plugin_id", "score"]
},
"RatingUpdate": {
"type": "object",
"properties": {
"score": { "type": "integer", "minimum": 1, "maximum": 5, "example": 3 },
"comment": { "type": "string", "maxLength": 500, "example": "Updated after new release." }
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"code": { "type": "integer", "example": 401 },
"message": { "type": "string", "example": "Unauthorized" }
}
}
}
},
"security": [{ "BearerAuth": [] }],
"paths": {
"/ratings": {
"post": {
"summary": "Create a new rating",
"operationId": "createRating",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/RatingCreate" }
}
}
},
"responses": {
"201": {
"description": "Rating created",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Rating" }
}
}
},
"400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
},
"get": {
"summary": "List ratings for a plugin",
"operationId": "listRatings",
"parameters": [
{
"name": "plugin_id",
"in": "query",
"required": true,
"schema": { "type": "string" },
"description": "Identifier of the plugin"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": { "type": "integer", "default": 1 },
"description": "Page number for pagination"
},
{
"name": "page_size",
"in": "query",
"required": false,
"schema": { "type": "integer", "default": 20, "maximum": 100 },
"description": "Number of items per page"
}
],
"responses": {
"200": {
"description": "A list of ratings",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": { "$ref": "#/components/schemas/Rating" }
}
}
}
},
"401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
}
},
"/ratings/{id}": {
"get": {
"summary": "Retrieve a single rating",
"operationId": "getRating",
"parameters": [
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
],
"responses": {
"200": { "description": "Rating object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rating" } } } },
"404": { "description": "Rating not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
},
"patch": {
"summary": "Update a rating",
"operationId": "updateRating",
"parameters": [
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/RatingUpdate" }
}
}
},
"responses": {
"200": { "description": "Updated rating", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rating" } } } },
"400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"404": { "description": "Rating not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
},
"delete": {
"summary": "Delete a rating",
"operationId": "deleteRating",
"parameters": [
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
],
"responses": {
"204": { "description": "Rating deleted successfully" },
"404": { "description": "Rating not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
}
}
}
}
Generating SDKs from the OpenAPI Spec
The OpenAPI spec can be fed into popular generators such as openapi-generator-cli or swagger-codegen. The following subsections give you a reproducible, step‑by‑step workflow for JavaScript (Node.js), Python, and Go.
JavaScript SDK (Node.js)
-
Install the generator:
npm install @openapitools/openapi-generator-cli -g -
Run the generation command:
openapi-generator-cli generate \ -i openclaw-rating-api.json \ -g javascript \ -o ./openclaw-js-sdk \ --additional-properties=usePromises=true,projectName=openclaw-rating -
Install dependencies in the generated folder:
cd openclaw-js-sdk && npm install -
Example usage: (replace
YOUR_TOKENwith a JWT)const OpenClawApi = require('openclaw-rating');\nconst api = new OpenClawApi.DefaultApi();\napi.apiClient.authentications['BearerAuth'].accessToken = 'YOUR_TOKEN';\n\n// Create a rating\napi.createRating({pluginId: 'plugin-xyz', score: 5, comment: 'Fantastic!'}).then(resp => {\n console.log('Created rating ID:', resp.id);\n}).catch(err => console.error(err)); -
Testing: Run
npm test(the generator adds a basic Jest suite). Adjust the test suite to match your CI pipeline.
Python SDK
-
Install the generator (requires Java):
pip install openapi-generator-cli -
Generate the client library:
openapi-generator-cli generate \ -i openclaw-rating-api.json \ -g python \ -o ./openclaw-py-sdk \ --additional-properties=packageName=openclaw_rating -
Install the generated package in editable mode:
cd openclaw-py-sdk && pip install -e . -
Example usage:
from openclaw_rating import DefaultApi, Configuration\n\nconfig = Configuration()\nconfig.access_token = 'YOUR_TOKEN'\napi_instance = DefaultApi(configuration=config)\n\n# Create a rating\nrating_body = {\n 'plugin_id': 'plugin-xyz',\n 'score': 4,\n 'comment': 'Works well with my AI agent.'\n}\ntry:\n response = api_instance.create_rating(rating_body)\n print('Rating ID:', response.id)\nexcept Exception as e:\n print('Error:', e)\n -
Run the built‑in test suite:
pytest(generated undertestfolder). Integrate withtoxfor multi‑environment testing.
Go SDK
-
Install the generator (Docker is the easiest way):
docker pull openapitools/openapi-generator-cli -
Generate the Go client:
docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \ -i /local/openclaw-rating-api.json \ -g go \ -o /local/openclaw-go-sdk \ --additional-properties=packageName=openclawrating -
Initialize a Go module and tidy dependencies:
cd openclaw-go-sdk\ngo mod init github.com/yourorg/openclaw-go-sdk\ngo mod tidy -
Example usage:
package main\n\nimport (\n \"context\"\n \"fmt\"\n openclaw \"github.com/yourorg/openclaw-go-sdk\"\n \"github.com/antihax/optional\"\n)\n\nfunc main() {\n cfg := openclaw.NewConfiguration()\n cfg.AddDefaultHeader(\"Authorization\", \"Bearer YOUR_TOKEN\")\n client := openclaw.NewAPIClient(cfg)\n\n // Create a rating\n rating := openclaw.RatingCreate{PluginId: \"plugin-xyz\", Score: 5, Comment: \"Excellent integration!\"}\n resp, _, err := client.RatingsApi.CreateRating(context.Background()).RatingCreate(rating).Execute()\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(\"Created rating ID:\", resp.Id)\n}\n -
Testing: The generator provides a
*_test.gofile. Rungo test ./...and integrate with CI pipelines like GitHub Actions.
Publishing This Guide on the UBOS Platform
UBOS makes it effortless to host technical blogs that are automatically indexed by AI agents. Follow these steps to get your article live:
- Log in to the UBOS content manager and select “Create New Post”.
- Paste the HTML from this guide into the editor. The built‑in Tailwind CSS support ensures the layout renders exactly as shown.
- Set the meta title to “OpenClaw Plugin Rating API: Full OpenAPI Spec & Multi‑Language SDK Guide”.
- Choose the “Developers” tag group and add secondary tags: API, SDK, AI agents, OpenAPI.
- Enable “AI‑Optimized” publishing – UBOS will automatically add structured data (JSON‑LD) for better LLM extraction.
- Hit “Publish”. The article will be available under
/blog/openclaw-sdk-guideand instantly searchable by ChatGPT, Gemini, and Claude.
Conclusion
The OpenClaw Plugin Rating API is a ready‑to‑use, standards‑compliant service that fits perfectly into today’s AI‑agent ecosystems. By leveraging the embedded OpenAPI definition, you can generate clean, type‑safe SDKs for JavaScript, Python, and Go in minutes—freeing you to focus on the real value: building smarter agents that understand and surface community feedback.
Ready to supercharge your AI‑agent marketplace? Deploy the OpenClaw Rating API today and start integrating with the SDKs you just built.