API Reference

Overview

The OpenCoWork API is a plain REST API. Every endpoint lives under /api/v1 on your deployment origin — set BASE to that origin in the examples below. Responses are JSON with camelCase property names; properties with null values are omitted.

The catalog has four content types — mcp, skill, agent and soul — that share identical read routes: swap the {type} segment and everything else stays the same. Each response carries an x-correlation-id header you can quote when reporting issues.

BASE="https://your-host"

# Liveness
curl "$BASE/health"
# -> ok

# First page of published MCP servers (no auth needed)
curl "$BASE/api/v1/mcp?page=1&pageSize=5"

Authentication & rate limits

All catalog read endpoints are public — no credentials needed. Write endpoints (reports, publishing, key management) require an API key. Create one in Console → API Keys; the full token (prefix ock_) is shown exactly once at creation. Send it as a standard bearer token.

API-key requests count against a daily quota shared by all keys of the same account. Every authenticated response returns X-RateLimit-Limit and X-RateLimit-Remaining headers; when the quota is exhausted the API returns 429 until 00:00 UTC. Request a higher quota from the console.

export OCW_KEY="ock_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

curl "$BASE/api/v1/auth/me" \
  -H "Authorization: Bearer $OCW_KEY"
# -> { "id": "…", "name": "…", "roles": ["Publisher"], "permissions": […], "isAdmin": false }

Errors

Errors use RFC 7807 problem details. The title field carries a stable, dot-separated error code (for example Mcp.NotFound) and detail carries a human-readable message. Match on title, not on detail.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Mcp.NotFound",
  "status": 404,
  "detail": "MCP server not found."
}

Pagination

List endpoints take page (default 1) and pageSize (default 20, max 100) and return a fixed envelope.

{
  "items": [ … ],
  "page": 1,
  "pageSize": 20,
  "total": 68,
  "hasNext": true
}

Catalog (read)

Public, read-only access to published items. Replace {type} with mcp, skill, agent or soul. Item summaries share a common shape (id, slug, name, summary, iconUrl, publisherName, source, isOfficial, isFeatured, installCount, viewCount, ratingAverage, tags, categories, updatedAt, publishedAt); MCP adds primaryTransport and toolCount, Skill adds executesCode.

Version detail is type-specific: MCP versions include connections, tools, resources, prompts, configFields and permissions; Skill versions include bundleFiles, dependencies, examples and parameters; Agent and Soul versions carry metadata only (readme, license, sourceUrl, packageUrl, checksum).

curl "$BASE/api/v1/mcp?search=github&sort=popular&pageSize=3"

[
  { "slug": "developer", "name": "Developer Tools", "count": 37 },
  { "slug": "productivity", "name": "Productivity", "count": 16 }
]

curl "$BASE/api/v1/skill/pdf-processing"

curl -i "$BASE/api/v1/soul/seneca-stoic/prompt.txt"
# Content-Type: text/markdown; charset=utf-8
#
# # Seneca
# > Stoic mentor persona
#
# You are Seneca…

Telemetry

If you redistribute catalog items (an IDE plugin, an agent runtime, a proxy), report usage events so install and usage counts stay meaningful. The endpoint is anonymous. clientId is any stable opaque string for the end device; the server stores only a truncated SHA-256 of it (or of the caller IP when omitted) for deduplication — never the raw value.

curl -X POST "$BASE/api/v1/telemetry" \
  -H "Content-Type: application/json" \
  -d '{ "itemType": "mcp", "slug": "github-mcp", "eventType": "install", "clientId": "device-8f2c" }'
# -> { "recorded": true }

API keys

Manage the keys of the authenticated account. Any authenticated caller (console session or an existing API key) may use these.

Publishing

Programmatic publishing requires the Publisher role on your account. The flow for every type: create a draft (with its first version) → update the draft → add versions → submit for review → moderators approve or request changes → withdraw at any time before a decision. Item status moves through draft → in_review → published (or changes_requested / rejected).

Skills are upload-only: after creating a version, upload the .zip package; SKILL.md inside the bundle is parsed at submit time.

curl -X POST "$BASE/api/v1/publisher/skill/$SKILL_ID/versions/$VERSION_ID/package" \
  -H "Authorization: Bearer $OCW_KEY" \
  -F "file=@my-skill.zip"