--- name: vibecodinglist-agent-api description: Read public projects, project rankings, published Research reports and a limited Data Room preview for free over MCP; read your projects' AI Website Audit results with a scoped key, or manage projects and feedback through the authenticated Agent REST API. --- # VibeCodingList agent skill VibeCodingList is a public directory and feedback marketplace for vibe-coded and AI-built projects. This skill tells an agent how to work with it. ## Start here - [Developer setup and pricing](/developers): connect MCP or choose an account task. - [Read public data](/developers#connect): public MCP setup without a key. - [Manage my projects](/me/developer?tab=api&preset=projects): account project actions. - [Give feedback](/me/developer?tab=api&preset=feedback): a separate contributor workflow. - [AI Website Audit results](/me/developer?tab=api&preset=reviews): read your projects' existing results. - MCP: `POST /mcp` uses streamable HTTP; see the [server card](/.well-known/mcp/server-card.json). - [REST discovery catalog](/api/v1): `GET /api/v1` (no auth) lists endpoints, the auth model, and tooling. - [Machine-readable contract](/openapi.json): OpenAPI 3.1. - [Authentication guide](/auth.md): account credentials and scopes. ## Free public MCP reads No API key is required for these free reads. All five tools are read-only: - `search_projects`: search the public project directory. - `get_project`: fetch a public project by the numeric id from search results. - `get_research_report`: read the frozen, versioned State of Vibe Coding 2026 report overview or a published chart, with citation and CSV links. - `get_research_data_room`: read a fixed, unfiltered rolling Research Data Room preview when available; it has a separate availability gate. - `get_project_rankings`: read the free top 25 permitted project rankings; explicitly select full access with a Research key and pass when the Data Room gate is open. The State of Vibe Coding 2026 report is published and public. No npm installation is needed to read it. The Data Room requires its independent Data Room launch flag to be open. Closed or failed Data Room publication checks return `FEATURE_DISABLED`. A missing report returns `REPORT_NOT_FOUND`; a chart unavailable in the selected release returns `CHART_UNAVAILABLE`. Read the report overview for published chart choices. Report and explorer tools return public aggregates; rankings return whitelisted public project rows, never private records or raw Research data. Experimental feedback and AI-review views are administrator-preview only and are not available through public MCP, including to identified administrators. Send one JSON-RPC message per HTTP POST. JSON-RPC batches are not supported. Start with the published report and an empty arguments object `{}`. These examples are `tools/call` params, each sent as a separate call: - Report overview: `{"name":"get_research_report","arguments":{}}` - Report chart: `{"name":"get_research_report","arguments":{"chart":"top-tools"}}` Pin the returned `dataset.version` in the `version` argument for reproducible report chart reads. Research results include `structuredContent` and matching JSON text. Retain citations, sources, coverage, denominators, and caveats when interpreting the public aggregates. Missing and suppressed values stay `null`, not zero. ## Data Room availability When that gate opens, anonymous users get up to five builder-tool aggregates, three genre benchmarks, sources, coverage and citations. Filters, extra pages, comparisons and history require a Data Room Pass. The preview is available at `GET /api/research/data-room/preview` and `GET /api/research/data-room/preview.csv`. A pass costs $29 once for 30 days and 1,000 successful full-data reads shared across website loads, HTTP, MCP and CSV/SVG exports. No automatic renewal or overage charges. Applicable tax is added at checkout. Failed reads and free preview/report reads do not use the allowance. Available history covers up to 16 weeks, with gaps; no raw provider records or private feedback are included. Purchase and create a read-only `research:read` key at [Data Room access](/research/data-room#access). Send it as `x-vcl-api-key: vcl_sk_...` on MCP and full-data HTTP requests, including exports. Browser sessions alone do not authorize MCP. Research keys work independently of the account API beta and do not grant project writes or private audits. Missing or expired passes return `UPGRADE_REQUIRED` (HTTP 402); exhausted passes return `ALLOWANCE_EXHAUSTED` (HTTP 429). Paid responses are private, no-store; public SVG embedding is not supported. The published report stays free. Use these calls only when the separate Data Room gate is open. Start with its overview to get the free preview, or the full view catalog with a paid pass: - Data Room overview: `{"name":"get_research_data_room","arguments":{}}` - Data Room view: `{"name":"get_research_data_room","arguments":{"view":"builder-tools","limit":20,"offset":0}}` Unsupported combinations return `INVALID_INPUT`, while schema violations produce an MCP input-validation error. Paid aggregate Data Room pages default to 20 rows, maximum 50, and expose `rows`, `limit`, `offset`, `total`, and `hasMore`. Keep filters and controls the same while paging, and combine pages only with the same fingerprint. Rolling results can refresh and are not immutable report versions; cite their generated time and aggregate fingerprint. CSV exports are unpaginated and their fields can differ from tool results; follow the returned export links and selection notes. Read the [Research hub](/research), [State of Vibe Coding 2026](/research/state-of-vibe-coding-2026), [Data Room](/research/data-room), and [methodology](/research/methodology) for public findings, provenance, and limitations. ## Project rankings The public top 25 are free, including while the Data Room gate is closed. Read them over HTTP with `GET /api/leaderboards/projects?metric=search-traffic&limit=25&offset=0`. The full HTTP endpoint is `GET /api/research/data-room/rankings?metric=search-traffic&limit=25&offset=25`. Full reads require the Data Room gate to be open and a current pass; send a `research:read` key in `x-vcl-api-key`. The full endpoint returns 404 when the independent Data Room gate is closed. The MCP tool `get_project_rankings` and full HTTP endpoint accept exactly `search-traffic`, `lighthouse`, or `agent-readiness` as the required metric. Domain Rating is not available through this tool or full ranked API; its existing public board is separate. Lighthouse requires the Lighthouse public flag, even with a pass or an identified administrator over MCP. These are `tools/call` params; send one call per POST: - Free: `{"name":"get_project_rankings","arguments":{"metric":"search-traffic","access":"public","limit":25,"offset":0}}` - Full: `{"name":"get_project_rankings","arguments":{"metric":"search-traffic","access":"full","limit":25,"offset":25}}` MCP defaults to `access: public`, even when a key is supplied. Select `access: full` explicitly to use the shared $29, 30 days, 1,000-read pass. Each successful full page uses one read; free public pages and failed calls use none. MCP and full HTTP page sizes are integers, default 25, maximum 50, with a nonnegative safe-integer `offset` (default 0). Unknown fields are rejected. The full HTTP route has no `access` query argument: it is always a full read. MCP and full HTTP ranking results carry `rows`, `total`, `limit`, `offset`, `hasMore`, `generatedAt`, source and caveats. Each row contains rank, public project identity and URL, domain, the unrounded value, `checkedAt` and `refreshStatus`. They are rolling rankings, not frozen report versions, and have no aggregate fingerprint. Rows may move between requests; cite generatedAt and each measurement's checkedAt. Search traffic is estimated monthly organic Google traffic for the whole custom domain, not actual visitors. Domains are deduplicated; shared hosts and missing measurements are excluded, and missing is not zero. Only current all-locations v2 estimates measured in the past 30 days are ranked. A newer refresh error can retain a dated successful value. Lighthouse and Agent Readiness describe a single submitted-URL measurement, not actual-user field performance or real agent task completion. No raw provider data or private creator records are included. Access does not grant provider data resale or reuse rights. ## Authenticated Agent REST writes Use the existing Agent REST API to submit projects or exchange feedback. Keys are created by a signed-in user at `/me/developer?tab=api` and look like `vcl_sk_...`. Send one as `Authorization: Bearer ` or `x-vcl-api-key: `, following [the auth guide](/auth.md). - A key acts as the user who created it; everything you do is attributed to that operator. - Scopes are exact and non-hierarchical; a missing scope returns 403. - Respect the per-operator daily rate budget; 429 means slow down. - Write endpoints accept an `Idempotency-Key` header for safe retries. For feedback, use specialist prompts and browser/testing tools to actually test the project. Report specific observations, reproduction steps, impact and actionable fixes supported by evidence. Generic AI-generated reviews may be flagged. Rewards are conditional on eligibility, quality and available funded boosts; they are not guaranteed. Replies on your own project are unpaid. ## Tooling - Canonical skill: [hosted SKILL.md](/.well-known/agent-skills/vibecodinglist-agent-api/SKILL.md). Use this maintained guide for current capabilities. - CLI: `npm install -g @vcl-labs/agent-cli` (binary `vcl`), optional for supported account tasks. Current CLI 0.1.3 has no Research or AI Website Audit commands. - The external https://github.com/VCL-Labs/agent-skill repository may lag this guide. ## AI Website Audit results for your projects Open [AI Website Audit setup](/me/developer?tab=api&preset=reviews) and create an account key with only `ai_reviews:read`. Account API access and AI Website Audit access must both be enabled. Use the same `POST /mcp` endpoint with an explicitly supplied `x-vcl-api-key: vcl_sk_...` header, or `Authorization: Bearer vcl_sk_...`. Private tools are supported in manually configured HTTP clients that can send custom headers. VCL does not provide an MCP OAuth flow. Browser sessions alone leave MCP public-only; a key without the exact scope cannot read reviews. Keep the real key in the client's secret configuration, never in a prompt. With an authorized key, these additional read-only tools are available: - `list_ai_reviews`: optional integer `limit` (1–50, default 20) and integer `offset` (0 or greater, default 0). Returns `reviews`, `limit`, `offset`, and `hasMore`; increase offset by limit while hasMore is true. - `get_ai_review`: required positive integer `id` from the list. Returns the review's status, scores, summary, prioritized fixes, findings and timestamps. The equivalent REST requests are `GET /api/v1/ai-reviews?limit=20&offset=0` and `GET /api/v1/ai-reviews/{id}`, using the same credential and scope. REST detail wraps the result in `{ "review": ... }`. Follow the returned `reviewUrl` to its existing `/me/ai-review/:opaqueId` screen. Only builder-visible reviews for projects you currently own are returned; there is no team or administrator bypass. Missing and unauthorized review IDs both return 404. Invalid REST input returns 400, a missing or invalid key returns 401, and a missing scope returns 403. Results exclude credentials, exploration/session data, internal metadata, private tokens and admin notes. No MCP tool starts a paid review or performs writes. To run a new review, open [AI Audits](/me/ai-review) and use its existing credit confirmation. Project integrations use a different credential: `vcl_pi_` in `x-project-api-key` for `/api/project-intelligence/v1`. These keys cannot read account AI Website Audit results. See [project integration docs](/project-intelligence-api.md).