{ "openapi": "3.1.0", "info": { "title": "Commonset Developer API", "version": "1.1.0", "description": "Use the Commonset API to discover and retrieve governed AI capabilities, create capability drafts, propose new versions, and submit versions for review. Access is scoped to the authenticated user and organization. Drafts and review submissions do not approve, publish, or execute capabilities. Existing Commonset developer tokens authenticate API requests; use trusted server-side clients and keep tokens private. Native repository instruction paths such as AGENTS.md are preserved on reads." }, "servers": [ { "url": "/api/v1", "description": "Current Commonset application origin" } ], "security": [ { "developerToken": [] } ], "tags": [ { "name": "Capabilities", "description": "Read authorized capabilities and verified immutable packages" }, { "name": "Workflow", "description": "Managed versions, authored drafts and human review submission; requires existing Commonset grants" } ], "paths": { "/openapi.json": { "get": { "tags": [ "Reference" ], "operationId": "getOpenApi", "summary": "Fetch public OpenAPI specification", "security": [], "responses": { "200": { "description": "API schema", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/capabilities/": { "get": { "tags": [ "Capabilities" ], "operationId": "listCapabilities", "summary": "List or search available capabilities", "description": "Bearer authentication uses a Commonset developer token bound to an organization. Results are limited to currently trusted, user-available canonical versions; creator-only drafts can appear for their creators.", "parameters": [ { "name": "q", "in": "query", "description": "Optional case-insensitive substring search of slug, name, description, and capability type", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "count", "limit" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "count": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Workflow" ], "operationId": "createCapabilityDraft", "summary": "Create a private, security-checked capability draft", "description": "Commonset developer bearer token from one organization. The caller becomes owner. The initial draft is private by default; organization metadata visibility must be explicitly requested. This creates SKILL.md-formatted capabilities, not native AGENTS.md imports.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftCreateRequest" } } } }, "responses": { "201": { "description": "Operation succeeded. This does not confer organization approval or publish the version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResult" } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/capabilities/{slug}/": { "get": { "tags": [ "Capabilities" ], "operationId": "getCapability", "summary": "Read trusted capability metadata, instructions and file manifest", "description": "Bearer authentication uses a Commonset developer token bound to an organization. Results are limited to currently trusted, user-available canonical versions; creator-only drafts can appear for their creators.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "description": "Exact semantic version or immutable version UUID. Never falls back to a different version.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Capability" } } } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/capabilities/{slug}/package/": { "get": { "tags": [ "Capabilities" ], "operationId": "getCapabilityPackage", "summary": "Read a verified, format-preserving, exact-version package", "description": "Bearer authentication uses a Commonset developer token bound to an organization. Results are limited to currently trusted, user-available canonical versions; creator-only drafts can appear for their creators.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "description": "Exact semantic version or immutable version UUID. Never falls back to a different version.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "capability", "package", "version_selection" ], "properties": { "capability": { "$ref": "#/components/schemas/Capability" }, "package": { "type": "object", "required": [ "format", "file_count", "total_bytes", "files" ], "properties": { "format": { "type": "string" }, "file_count": { "type": "integer" }, "total_bytes": { "type": "integer" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/PackageFile" } } } }, "version_selection": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit", "latest_available" ] }, "requested": { "type": "string" }, "resolved": { "type": "string" }, "resolved_version_id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/managed-capabilities/": { "get": { "tags": [ "Workflow" ], "operationId": "listManagedCapabilities", "summary": "List capabilities the user may manage and their latest version IDs", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Managed capability metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "capabilities", "count" ], "properties": { "capabilities": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" } } } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/capabilities/{slug}/status/": { "get": { "tags": [ "Workflow" ], "operationId": "getCapabilityStatus", "summary": "Get current review, trust and publication-gate status", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "version", "in": "query", "description": "Exact version string or UUID; optional.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Actor-authorized lifecycle state", "content": { "application/json": { "schema": { "type": "object", "required": [ "registration", "capability", "version", "review", "trust", "availability", "publication" ] } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/capabilities/{slug}/versions/": { "post": { "tags": [ "Workflow" ], "operationId": "createCapabilityVersionDraft", "summary": "Create a new draft version from an explicitly pinned base", "description": "Commonset developer bearer token from one organization. Requires MANAGE permission. Inherits unchanged files, checks against the currently latest immutable base under the existing authoring lock, and does not overwrite approved versions.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionDraftRequest" } } } }, "responses": { "201": { "description": "Operation succeeded. This does not confer organization approval or publish the version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResult" } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/capabilities/{slug}/versions/{version_id}/reviews/": { "post": { "tags": [ "Workflow" ], "operationId": "submitCapabilityForReview", "summary": "Submit an exact capability version for human review", "description": "Commonset developer bearer token from one organization. Requires MANAGE permission and the review service's trust and lifecycle checks. Repeated submissions of an open review round return 409; no approve or publish API exists.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "version_id", "in": "path", "required": true, "description": "Exact Commonset immutable version UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewSubmitRequest" } } } }, "responses": { "201": { "description": "Operation succeeded. This does not confer organization approval or publish the version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewSubmissionResult" } } } }, "400": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Structured API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "developerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Commonset developer token", "description": "Generate/revoke at /mcp/access/ for an organization. Store outside source control. MCP OAuth tokens are not valid for this REST resource." } }, "schemas": { "Capability": { "type": "object", "required": [ "id", "slug", "name", "description", "capability_type", "version", "version_id", "review_status", "organization_approved", "trust", "availability" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "capability_type": { "type": "string", "description": "Provider-neutral Commonset type, such as skill, agent, instruction, tool, or workflow" }, "capability_type_label": { "type": "string" }, "owner": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user", "group", "unassigned" ] }, "display_name": { "type": "string" } } }, "version": { "type": "string" }, "version_id": { "type": "string", "format": "uuid" }, "content_hash": { "type": "string" }, "registration_status": { "type": "string" }, "review_status": { "type": "string" }, "security_status": { "type": "string" }, "organization_approved": { "type": "boolean", "description": "False for creator-available draft versions" }, "trust": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string" } } }, "availability": { "type": "object", "properties": { "available": { "type": "boolean" }, "scope": { "type": "string" }, "label": { "type": "string" }, "reason": { "type": "string" } } }, "entrypoint": { "type": "string", "description": "Physical entrypoint file path. Native instruction capabilities preserve AGENTS.md, CLAUDE.md, and other source Markdown paths rather than requiring SKILL.md." }, "instructions": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityFile" } }, "provenance": { "description": "Curated source provenance; null when no source record exists. Opaque provider metadata is excluded.", "oneOf": [ { "$ref": "#/components/schemas/CapabilityProvenance" }, { "type": "null" } ] } } }, "CapabilityFile": { "type": "object", "required": [ "path", "sha256", "size" ], "properties": { "path": { "type": "string" }, "sha256": { "type": "string" }, "size": { "type": "integer" }, "mime_type": { "type": "string" }, "is_script": { "type": "boolean" } } }, "PackageFile": { "type": "object", "required": [ "path", "size", "sha256", "content_encoding", "content" ], "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "mime_type": { "type": "string" }, "is_script": { "type": "boolean" }, "content_encoding": { "type": "string", "enum": [ "utf-8", "base64" ] }, "content": { "type": "string", "description": "UTF-8 text or base64 bytes; decode based on content_encoding" } } }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "CapabilityProvenance": { "type": "object", "required": [ "origin", "source_reference", "artifact_sha256", "recorded_at" ], "properties": { "origin": { "type": "string" }, "source_reference": { "type": "string", "description": "Original source reference; may be empty if not recorded." }, "artifact_sha256": { "type": "string" }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "SupportingTextFile": { "type": "object", "additionalProperties": false, "required": [ "path", "content" ], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Safe repository-relative file path except SKILL.md" }, "content": { "type": "string", "description": "UTF-8 supporting text. Files must stay within the documented request size limits." } } }, "DraftCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "description", "instructions" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 }, "instructions": { "type": "string", "minLength": 1, "description": "Text body; Commonset creates the SKILL.md entrypoint and runs normal security checks." }, "capability_type": { "type": "string", "enum": [ "skill", "routine", "workflow", "agent", "tool", "connector", "other" ], "default": "skill" }, "visibility": { "type": "string", "enum": [ "private", "organization" ], "default": "private", "description": "Private by default. Organization visibility exposes metadata but does not automatically grant file access." }, "version": { "type": "string", "maxLength": 32, "default": "0.1.0" }, "release_notes": { "type": "string", "maxLength": 8192 }, "files": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/SupportingTextFile" } } } }, "VersionDraftRequest": { "type": "object", "additionalProperties": false, "required": [ "base_version" ], "properties": { "base_version": { "type": "string", "format": "uuid", "description": "Required immutable ID of the latest version. 409 if it changed; prevents stale version creation." }, "description": { "type": "string", "maxLength": 4096 }, "instructions": { "type": "string", "description": "Optional replacement instructions; inherited when omitted." }, "version": { "type": "string", "maxLength": 32, "description": "Optional semantic version; defaults to next patch." }, "release_notes": { "type": "string", "maxLength": 8192 }, "files": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/SupportingTextFile" } } } }, "ReviewSubmitRequest": { "type": "object", "additionalProperties": false, "maxProperties": 0, "description": "An explicit empty JSON object. The immutable version UUID is in the path." }, "DraftResult": { "type": "object", "required": [ "capability", "message" ], "properties": { "capability": { "type": "object", "required": [ "slug", "version", "version_id", "status", "security_status", "availability_scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "capability_type": { "type": "string" }, "version": { "type": "string" }, "version_id": { "type": "string", "format": "uuid" }, "base_version": { "type": "string" }, "status": { "type": "string" }, "security_status": { "type": "string" }, "availability_scope": { "type": "string" }, "visibility": { "type": "string" } } }, "message": { "type": "string" } } }, "ReviewSubmissionResult": { "type": "object", "required": [ "capability", "version", "review", "message" ], "properties": { "capability": { "type": "object" }, "version": { "type": "object" }, "review": { "type": "object", "properties": { "review_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "round": { "type": "integer" }, "requested_at": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }