Sign in

VerWatch API.

Read your team's Craft CMS dependency state — projects, packages and updates — over a versioned REST API.

v1 Download the OpenAPI 3.1 spec

Getting started

API & MCP access is included in the Agency plan (and during the free trial). Requests from a team whose plan does not include API access get a 403.

  1. Open Settings → API / MCP.
  2. Create a token, name it, choose whether it may run updates, and copy the secret. It is shown only once, and starts with verwatch_.
  3. Send it as a bearer token on every request.

The base URL is https://verwatch.com/api/v1. A first request:

curl https://verwatch.com/api/v1/projects \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Authentication

A token belongs to a person and reaches every team they are on, never one they are not. Requests without a valid token get a 401.

Tokens carry the read ability, and optionally write, which is what lets an agent start an update run through the MCP server. Every endpoint in this reference is read-only, so a read token is all the REST API asks for. Writing still depends on the person's role on the team: a viewer's write token cannot start a run.

Choosing a team

Add ?team=<slug> to any request to say which team it is about. Without it, the request uses the person's default team, or failing that the first of their teams whose plan includes API access. GET /me lists every team the token can reach with its slug, so start there. A slug the person is not on, or a team on a plan without API access, gets a 403 with the reason.

Pagination

List endpoints are page-paginated. Control them with ?page= and ?per_page= (default 25, max 100). Responses carry data, links and meta blocks.

Rate limiting

Requests are limited to 60 per minute per person, shared across all of their tokens and the MCP server. Responses include X-RateLimit-Limit and X-RateLimit-Remaining; a 429 adds Retry-After.

Errors

Errors return a consistent JSON envelope — a message, plus an errors object for 422 validation failures.

{
  "message": "Unauthenticated."
}

Endpoints

  • GET /me

    The team this request resolved to, every team the token can reach, and the token itself.

  • GET /projects

    List the team's projects. Filters: outdated, source_type.

  • GET /projects/{owner}/{project}

    A single project by its path, the same org/repo pair as its GitHub URL.

  • GET /projects/{owner}/{project}/packages

    Packages in a project. Filters: outdated, critical.

  • GET /packages/{vendor}/{name}

    Cross-project view of one package.

  • GET /updates

    Update requests. Filters: project, status.

  • GET /updates/{update}

    A single update request with its pull requests.

Model Context Protocol (MCP)

The same data is available to AI agents over an MCP server at https://verwatch.com/api/mcp, authenticated with the same personal access tokens: seven tools read (list-teams, list-projects, get-project, list-project-packages, get-package, list-updates, get-update) and one writes. Every tool takes an optional team slug and otherwise works on the person's default team; a client can also pin one by adding ?team=<slug> to the server URL.

run-update starts an update run for a project, and needs a token with the write ability. It opens pull requests against your repository and merges them if the call asks it to, so it will not start until it is told how far to carry the run, using the same three options as the Run Updates button: Open PRs, Merge staging, or Merge both. A run takes several minutes, so the tool returns an update id and the versions it expects to change, and the versions it actually changed arrive on get-update once the run finishes.