API & automation#

rickub exposes a token-authenticated JSON API and a hosted MCP endpoint, so scripts, services, and AI agents can drive it.

Get a token#

Create a personal access token under Settings → Access tokens. Send it as a bearer token on every request.

Base URL & shape#

The JSON API is versioned and lives under /api/v1. Requests and responses are JSON:

# Who am I?
curl -H "Authorization: Bearer $RICKUB_TOKEN" \
  https://rickub.com/api/v1/user

# Create a repository
curl -X POST \
  -H "Authorization: Bearer $RICKUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-project","visibility":"private"}' \
  https://rickub.com/api/v1/repos

# List a repository's merge requests
curl -H "Authorization: Bearer $RICKUB_TOKEN" \
  https://rickub.com/api/v1/repos/your-handle/my-project/merge-requests

# Comment on ONE LINE of a merge request's diff (needs write access)
curl -X POST \
  -H "Authorization: Bearer $RICKUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file":"web/api.go","line":128,"side":"new","intent":"request_change","body":"guard the nil case"}' \
  https://rickub.com/api/v1/repos/your-handle/my-project/merge-requests/11/line-comments

Endpoints cover repositories (including archive and tag creation), collaborators, merge requests (with line-anchored review comments), issues, releases, webhooks, CI runs and artifacts, organizations, code contents, and search — the same surface the CLI is built on.

REST reference#

The complete REST reference — every path, parameter, request and response shape — is the OpenAPI document served at docs/api/openapi.yaml. Fetch it and explore it with any OpenAPI tooling:

curl -sS https://rickub.com/docs/api/openapi.yaml -o rickub-openapi.yaml

The document is the machine-readable source the API is built from; this page's examples are the short tour, not the contract.

Review comments can be anchored to a file and line, not just to the merge request as a whole: GET/POST /line-comments and POST /line-comments/:id/resolve. Each carries a side (new or old) and an intent — info, request_change, or kudos — and threads via parent_id. The same operations are available as rickub pr comment --file … --line … and as MCP tools, so a reviewing agent can point at the exact line.

Hosted MCP endpoint#

For AI agents and integrations, rickub hosts a Model Context Protocol endpoint at /api/mcp. It uses the same bearer-token authentication as the JSON API, so an agent with a token can read and act on your repositories through a standard MCP client.

Point a config-file MCP client (e.g. Claude Desktop or Claude Code) at the remote endpoint, passing your token as a bearer credential:

{
  "mcpServers": {
    "rickub": {
      "url": "https://rickub.com/api/mcp",
      "headers": { "Authorization": "Bearer rickub_pat_xxx" }
    }
  }
}

Or drive it directly over Streamable HTTP (JSON-RPC 2.0) — list the tools, then call one:

# list the available tools
curl -sS https://rickub.com/api/mcp \
  -H "Authorization: Bearer $RICKUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# call a tool — here, read a repository's metadata
curl -sS https://rickub.com/api/mcp \
  -H "Authorization: Bearer $RICKUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_repo","arguments":{"owner":"acme","repo":"api"}}}'

Tools cover the same surface as the API — e.g. get_repo, list_dir, get_file, create_merge_request, list_merge_requests, dispatch_workflow, get_run_logs, and search_repos. The MCP server page walks through connecting Claude Code, Cursor and other clients, and lists the full tool set.