### GET /apps (Filtering Example)

Source: https://docs.gummble.com/docs/api

Demonstrates query-string filtering. Repeat keys to OR-combine filters.

```APIDOC
## GET /apps

### Description
Fetches apps filtered by category and platform. Repeat keys to OR-combine filters.

### Method
GET

### Endpoint
/apps

### Parameters
#### Query Parameters
- **category** (string) - Optional - Filter by category. Can be repeated to OR-combine.
- **platform** (string) - Optional - Filter by platform.

### Request Example
GET /apps?category=Finance&category=Travel&platform=ios

### Response
#### Success Response (200)
- **data** (array) - List of apps matching the filters.

#### Response Example
{
  "data": [...]
}
```

--------------------------------

### Get an app example with curl

Source: https://docs.gummble.com/docs/api/apps

Example request to fetch a specific app by slug (linear) using curl with an authorization header.

```bash
curl https://api.gummble.com/api/v1/apps/linear \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /apps (Pagination Example)

Source: https://docs.gummble.com/docs/api

Demonstrates cursor-based pagination for collection endpoints. The limit parameter defaults to 20 and max is 100. Pass the cursor from the previous response to advance.

```APIDOC
## GET /apps

### Description
Fetches a paginated list of apps from the catalogue.

### Method
GET

### Endpoint
/apps

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of items per page. Defaults to 20, max 100.
- **cursor** (string) - Optional - Cursor from the previous response to advance to the next page.

### Request Example
GET /apps?limit=20&cursor=eyJpZCI6...

### Response
#### Success Response (200)
- **data** (array) - List of apps.
- **pagination** (object) - Pagination metadata.
  - **cursor** (string) - Cursor for the next page.
  - **hasMore** (boolean) - Whether more items are available.
  - **total** (integer) - Total number of items.

#### Response Example
{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6...",
    "hasMore": true,
    "total": 1247
  }
}
```

--------------------------------

### List apps example with curl and response

Source: https://docs.gummble.com/docs/api/apps

Example request to list apps with a search query and limit, followed by the JSON response containing app data and pagination info.

```bash
curl 'https://api.gummble.com/api/v1/apps?q=linear&limit=1' \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "data": [{
    "id": "app_01HXY...",
    "slug": "linear",
    "name": "Linear",
    "platforms": ["web", "ios"],
    "categories": ["Productivity"],
    "iconUrl": "https://storage.gummble.com/apps/linear/icon.webp",
    "previewScreenIds": ["sc_…", "sc_…"]
  }],
  "pagination": { "cursor": "...", "hasMore": true }
}
```

--------------------------------

### Example prompt for Gummble MCP

Source: https://docs.gummble.com/docs/mcp/codex

An example of a prompt to use after the server is connected to leverage Gummble tools.

```text
Before building this paywall, use Gummble MCP to find 5 mobile paywalls
with annual discount framing and summarize the layout patterns.
```

--------------------------------

### Visual search curl example

Source: https://docs.gummble.com/docs/api/search

Example of uploading an image for visual search using curl.

```bash
curl -X POST https://api.gummble.com/api/v1/search/visual \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@screenshot.png" \
  -F "limit=10"
```

--------------------------------

### Filtering Request Example

Source: https://docs.gummble.com/docs/api

Example of query-string filtering with repeated keys to OR-combine filters.

```http
GET /apps?category=Finance&category=Travel&platform=ios
```

--------------------------------

### Pagination Response Example

Source: https://docs.gummble.com/docs/api

Example response structure for a paginated endpoint, showing the data array and pagination metadata.

```json
{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6...",
    "hasMore": true,
    "total": 1247
  }
}
```

--------------------------------

### Paginated Request Example

Source: https://docs.gummble.com/docs/api

Example of a cursor-based paginated request using the limit and cursor query parameters.

```http
GET /apps?limit=20&cursor=eyJpZCI6...
```

--------------------------------

### Follow-up prompt: search empty states

Source: https://docs.gummble.com/docs/mcp/getting-started

Follow-up prompt example for comparing search empty states and summarizing recovery actions.

```text
Compare search empty states from marketplace apps and summarize the
common recovery actions.
```

--------------------------------

### Add and authenticate Gummble MCP via Kilo CLI

Source: https://docs.gummble.com/docs/mcp/kilo-code

Adds the remote server and starts OAuth. Complete sign-in and consent in the browser.

```bash
kilo mcp add gummble --url https://mcp.gummble.com/mcp
kilo mcp auth gummble
```

--------------------------------

### Example API response

Source: https://docs.gummble.com/docs/quickstart

The expected JSON structure returned by the apps endpoint.

```json
{
  "data": [
    { "id": "app_…", "name": "Linear", "slug": "linear", … },
    …
  ],
  "pagination": { "cursor": "…", "hasMore": true }
}
```

--------------------------------

### First prompt for UI research

Source: https://docs.gummble.com/docs/mcp/getting-started

Example prompt to run after connecting the MCP server. The client should call Gummble tools and return app names, screen or flow references, source links, and a short synthesis.

```text
Use Gummble MCP to find 5 mobile onboarding screens from language
learning apps. Compare the first-step layout, CTA copy, and progress
framing.
```

--------------------------------

### RateLimit Response Headers

Source: https://docs.gummble.com/docs/api/rate-limits

Example of the standard headers included in every response to indicate current rate limit status.

```http
RateLimit-Limit: 60
RateLimit-Remaining: 42
RateLimit-Reset: 1779555000
```

--------------------------------

### Request fintech onboarding screens in Cursor chat

Source: https://docs.gummble.com/docs/mcp/cursor

Example chat request to use Gummble MCP to find fintech onboarding screens and cite the app for each result.

```text
Use Gummble MCP to find 3 fintech onboarding screens and cite the app for each result.
```

--------------------------------

### Follow-up prompt: annual plan discount framing

Source: https://docs.gummble.com/docs/mcp/getting-started

Follow-up prompt example for researching annual plan discount framing in mobile paywalls.

```text
Find examples of annual plan discount framing in mobile paywalls.
```

--------------------------------

### First bounded request for screen search

Source: https://docs.gummble.com/docs/mcp/tools

An example of a bounded request to the gummble_search_screens tool, specifying a query, platform, limit, and image inclusion preference.

```text
Call gummble_search_screens once with q "Calendly booking page select a
day and time slot calendar", platform "web", limit 3, and include_images
false. Return the app name and Gummble link for each result, then stop.
```

--------------------------------

### Refresh Token Request

Source: https://docs.gummble.com/docs/authentication

Example of using a refresh token to obtain a new access token. Requires the refresh token and client ID variables to be set.

```bash
curl -X POST https://api.gummble.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$RT" \
  -d "client_id=$CID" \
  -d "resource=https://mcp.gummble.com/mcp"
```

--------------------------------

### Get a screen endpoint

Source: https://docs.gummble.com/docs/api/screens

Retrieves details for a specific screen by its ID.

```http
GET /api/v1/screens/:id
```

--------------------------------

### GET /api/v1/screens/:id/download

Source: https://docs.gummble.com/docs/api/screens

Downloads a screen image. Requires a pro or team plan and returns a short-lived signed URL.

```APIDOC
## GET /api/v1/screens/:id/download

### Description
Downloads a screen image. Requires a pro or team plan and returns a short-lived signed URL.

### Method
GET

### Endpoint
/api/v1/screens/:id/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the screen.

### Response
#### Success Response (200)
Returns a short-lived signed URL.

```

--------------------------------

### GET /api/v1/screens

Source: https://docs.gummble.com/docs/api/screens

Lists screens with optional filters for app, UI pattern, dominant colors, and free-text search.

```APIDOC
## GET /api/v1/screens

### Description
Lists screens with optional filters for app, UI pattern, dominant colors, and free-text search.

### Method
GET

### Endpoint
/api/v1/screens

### Parameters
#### Query Parameters
- **appId** (string) - Optional - Filter by app
- **pattern** (string) - Optional - UI pattern (onboarding, paywall, empty-state, ...)
- **colors** (string[]) - Optional - Dominant color filter
- **q** (string) - Optional - Free-text on extracted OCR + caption

```

--------------------------------

### Copilot Chat verification prompt

Source: https://docs.gummble.com/docs/mcp/github-copilot

Example prompt to verify Gummble in Copilot Chat Agent mode.

```text
Use Gummble to find three web checkout screens with express-payment
options. Return the source links and compare their information hierarchy
before changing the code.
```

--------------------------------

### Follow-up prompt: checkout screens with Apple Pay

Source: https://docs.gummble.com/docs/mcp/getting-started

Follow-up prompt example for pulling checkout screens with Apple Pay and identifying trust badges or delivery promises.

```text
Pull 6 checkout screens with Apple Pay and identify where trust badges
or delivery promises appear.
```

--------------------------------

### GET /api/v1/screens/:id

Source: https://docs.gummble.com/docs/api/screens

Retrieves a single screen by its unique identifier.

```APIDOC
## GET /api/v1/screens/:id

### Description
Retrieves a single screen by its unique identifier.

### Method
GET

### Endpoint
/api/v1/screens/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the screen.

```

--------------------------------

### GET /api/v1/apps

Source: https://docs.gummble.com/docs/api/apps

Lists apps in the Gummble library with optional filtering by search query, category, platform, and pagination.

```APIDOC
## GET /api/v1/apps

### Description
Lists apps in the Gummble library. Supports free-text search, category filtering, platform filtering, and pagination.

### Method
GET

### Endpoint
/api/v1/apps

### Parameters
#### Query Parameters
- **q** (string) - Optional - Free-text search across name + slug
- **category** (string[]) - Optional - OR-filter on category names
- **platform** (`IOS` | `ANDROID` | `WEB`) - Optional - Platform filter; lowercase URL tokens are accepted and normalized
- **limit** (number) - Optional - Page size (default 20, max 100)
- **cursor** (string) - Optional - Pagination cursor

### Request Example
```
curl 'https://api.gummble.com/api/v1/apps?q=linear&limit=1' \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **data** (array) - List of app objects
  - **id** (string) - App ID (e.g., app_01HXY...)
  - **slug** (string) - App slug (e.g., 'linear')
  - **name** (string) - App name
  - **platforms** (string[]) - List of platforms (e.g., ["web", "ios"])
  - **categories** (string[]) - List of categories (e.g., ["Productivity"])
  - **iconUrl** (string) - URL to the app icon
  - **previewScreenIds** (string[]) - List of preview screen IDs
- **pagination** (object) - Pagination info
  - **cursor** (string) - Pagination cursor
  - **hasMore** (boolean) - Whether more results are available

#### Response Example
```
{
  "data": [{
    "id": "app_01HXY...",
    "slug": "linear",
    "name": "Linear",
    "platforms": ["web", "ios"],
    "categories": ["Productivity"],
    "iconUrl": "https://storage.gummble.com/apps/linear/icon.webp",
    "previewScreenIds": ["sc_…", "sc_…"]
  }],
  "pagination": { "cursor": "...", "hasMore": true }
}
```
```

--------------------------------

### GET /api/v1/flows

Source: https://docs.gummble.com/docs/api/flows

Lists flows, optionally filtered by app, type, or platform.

```APIDOC
## GET /api/v1/flows

### Description
Lists flows, optionally filtered by app, type, or platform.

### Method
GET

### Endpoint
/api/v1/flows

### Parameters
#### Query Parameters
- **appId** (string) - Optional - Filter by app
- **type** (string) - Optional - Flow type (`onboarding`, `paywall`, `checkout`, …)
- **platform** (`IOS` | `ANDROID` | `WEB`) - Optional - Platform filter; lowercase URL tokens are accepted and normalized

```

--------------------------------

### Universal search GET request

Source: https://docs.gummble.com/docs/api/search

Perform a hybrid search across apps, screens, or flows using the query parameter.

```http
GET /api/v1/search?q=onboarding&type=screen&limit=10
```

--------------------------------

### GET /api/v1/flows/:id

Source: https://docs.gummble.com/docs/api/flows

Returns a specific flow along with its ordered list of screen objects.

```APIDOC
## GET /api/v1/flows/:id

### Description
Returns the flow plus its ordered list of screen objects (full payload, not just IDs).

### Method
GET

### Endpoint
/api/v1/flows/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The flow ID

```

--------------------------------

### Get an app endpoint

Source: https://docs.gummble.com/docs/api/apps

Retrieves a single app by slug or ID, returning the full app payload including all screens and flows.

```http
GET /api/v1/apps/:slugOrId
```

--------------------------------

### GET /api/v1/apps/:slugOrId

Source: https://docs.gummble.com/docs/api/apps

Returns the full app payload including all screens and flows for a specific app identified by slug or ID.

```APIDOC
## GET /api/v1/apps/:slugOrId

### Description
Returns the full app payload including all screens and flows for a specific app identified by slug or ID.

### Method
GET

### Endpoint
/api/v1/apps/:slugOrId

### Parameters
#### Path Parameters
- **slugOrId** (string) - Required - The app slug or ID

### Request Example
```
curl https://api.gummble.com/api/v1/apps/linear \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (string) - App ID (e.g., app_01HXY...)
- **slug** (string) - App slug (e.g., 'linear')
- **name** (string) - App name
- **description** (string, optional) - App description
- **platform** (`IOS` | `ANDROID` | `WEB`) - App platform
- **categories** (string[]) - List of categories
- **iconUrl** (string) - URL to the app icon
- **websiteUrl** (string, optional) - App website URL
- **screens** (Screen[]) - List of screens (populated on GET /apps/:slug)
- **flows** (Flow[]) - List of flows (populated on GET /apps/:slug)
```

--------------------------------

### Get a flow

Source: https://docs.gummble.com/docs/api/flows

Returns a specific flow by ID, including its ordered list of screen objects (full payload, not just IDs).

```http
GET /api/v1/flows/:id
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://docs.gummble.com/docs/authentication

Retrieves the OAuth 2.1 server metadata document (RFC 8414). This endpoint provides configuration information about the authorization server, such as token endpoint, authorization endpoint, and supported scopes.

```APIDOC
## GET /.well-known/oauth-authorization-server

### Description
Retrieves the OAuth 2.1 server metadata document (RFC 8414). This endpoint provides configuration information about the authorization server, such as token endpoint, authorization endpoint, and supported scopes.

### Method
GET

### Endpoint
https://api.gummble.com/.well-known/oauth-authorization-server

### Response
#### Success Response (200)
- **issuer** (string) - The issuer identifier for the authorization server.
- **authorization_endpoint** (string) - The authorization endpoint URL.
- **token_endpoint** (string) - The token endpoint URL.
- **jwks_uri** (string) - The JWKS URI.
- **registration_endpoint** (string) - The dynamic client registration endpoint.
- **revocation_endpoint** (string) - The revocation endpoint.
- **scopes_supported** (array) - List of supported scopes.
- **code_challenge_methods_supported** (array) - List of supported PKCE code challenge methods.

#### Response Example
{
  "issuer": "https://api.gummble.com",
  "authorization_endpoint": "https://api.gummble.com/oauth/authorize",
  "token_endpoint": "https://api.gummble.com/oauth/token",
  "jwks_uri": "https://api.gummble.com/.well-known/jwks.json",
  "registration_endpoint": "https://api.gummble.com/oauth/register",
  "revocation_endpoint": "https://api.gummble.com/oauth/revoke",
  "scopes_supported": ["mcp:read", "mcp:tools"],
  "code_challenge_methods_supported": ["S256"]
}
```

--------------------------------

### Error Response Shape

Source: https://docs.gummble.com/docs/api

Example error response following a JSON-Problem-ish shape, including statusCode, error, message, timestamp, and path fields.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "App not found",
  "timestamp": "2026-05-23T16:00:00.000Z",
  "path": "/api/v1/apps/missing"
}
```

--------------------------------

### GET /oauth/authorize

Source: https://docs.gummble.com/docs/authentication

Initiates the authorization code flow (RFC 6749 §4.1.1, RFC 7636, RFC 8707). This endpoint is used to obtain user consent and redirect back to the client with an authorization code.

```APIDOC
## GET /oauth/authorize

### Description
Initiates the authorization code flow (RFC 6749 §4.1.1, RFC 7636, RFC 8707). This endpoint is used to obtain user consent and redirect back to the client with an authorization code.

### Method
GET

### Endpoint
https://api.gummble.com/oauth/authorize

### Parameters
#### Query Parameters
- **response_type** (string) - Required - Must be "code".
- **client_id** (string) - Required - The client identifier.
- **redirect_uri** (string) - Required - The redirect URI where the user is sent after authorization.
- **state** (string) - Required - A value used to maintain state between the request and callback.
- **code_challenge** (string) - Required - The PKCE code challenge (S256).
- **code_challenge_method** (string) - Required - Must be "S256".
- **resource** (string) - Required - The resource indicator (RFC 8707) for which the access token is requested.

### Response
#### Success Response (302)
- **code** (string) - The authorization code.
- **state** (string) - The state value echoed back.

#### Response Example
HTTP/1.1 302 Found
Location: http://127.0.0.1:8080/callback?code=...&state=...
```

--------------------------------

### GET /api/v1/search

Source: https://docs.gummble.com/docs/api/search

Performs hybrid keyword and semantic search across apps, screens, and flows. Supports filtering by result type and limiting the number of results.

```APIDOC
## GET /api/v1/search

### Description
Performs hybrid keyword and semantic search across apps, screens, and flows. Supports filtering by result type and limiting the number of results.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Query string
- **type** (`app` | `screen` | `flow` | `all`) - Optional - Result type filter
- **limit** (number) - Optional - Max results (default 10, max 50)
- **semantic** (boolean) - Optional - Force semantic-only mode (default: hybrid)

### Request Example
GET /api/v1/search?q=onboarding&type=screen&limit=10

### Response
#### Success Response (200)
- **data** (array) - List of search results
- **type** (string) - Result type (e.g., screen)
- **score** (number) - Similarity score (0-1)
- **item** (object) - Full Screen object

#### Response Example
{
  "data": [
    {
      "type": "screen",
      "score": 0.87,
      "item": { ... full Screen object ... }
    }
  ]
}
```

--------------------------------

### App object type definition

Source: https://docs.gummble.com/docs/api/apps

TypeScript type definition for the App object returned by the API. Note that screens and flows are only populated when fetching a single app via GET /apps/:slug.

```typescript
type App = {
  id: string                 // app_01HXY...
  slug: string               // 'linear'
  name: string
  description?: string
  platform: 'IOS' | 'ANDROID' | 'WEB'
  categories: string[]
  iconUrl: string
  websiteUrl?: string
  screens: Screen[]          // populated on GET /apps/:slug
  flows: Flow[]              // populated on GET /apps/:slug
}
```

--------------------------------

### GET /.well-known/jwks.json

Source: https://docs.gummble.com/docs/authentication

Retrieves the JSON Web Key Set (JWKS) containing the public signing keys used to verify tokens (RFC 7517). This endpoint is used by clients to validate the signature of access tokens.

```APIDOC
## GET /.well-known/jwks.json

### Description
Retrieves the JSON Web Key Set (JWKS) containing the public signing keys used to verify tokens (RFC 7517). This endpoint is used by clients to validate the signature of access tokens.

### Method
GET

### Endpoint
https://api.gummble.com/.well-known/jwks.json

### Response
#### Success Response (200)
- **keys** (array) - Array of JSON Web Keys.

#### Response Example
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "...",
      "n": "...",
      "e": "AQAB"
    }
  ]
}
```

--------------------------------

### Flow object type definition

Source: https://docs.gummble.com/docs/api/flows

TypeScript type definition for a Flow object. Fields include id, appId, type, name, optional description, ordered screenIds, optional screens (present on GET /flows/:id), and capturedAt.

```typescript
type Flow = {
  id: string
  appId: string
  type: string                   // 'onboarding'
  name: string                   // 'New user onboarding'
  description?: string
  screenIds: string[]            // ordered
  screens?: Screen[]             // present on GET /flows/:id
  capturedAt: string
}
```

--------------------------------

### Research prompt for onboarding flow sequences

Source: https://docs.gummble.com/docs/mcp/bolt

Use this prompt with Gummble to find browsable onboarding flow sequences for collaborative apps. It asks to compare steps, progress framing, permission timing, and first value, and to cite source links before implementing the flow.

```text
Use Gummble to find browsable onboarding flow sequences for collaborative apps.
Compare steps, progress framing, permission timing, and first value. Cite
the source links before implementing our flow.
```

--------------------------------

### Verify Gummble with a bounded task

Source: https://docs.gummble.com/docs/mcp/kiro

Use this prompt to test Gummble's read-only MCP tools by researching three real onboarding flows. Review the returned source links before approving broader tool access.

```text
Use Gummble to research three real onboarding flows for an AI note-taking
app. Compare the sequence, first-value moment, and source links before
proposing our implementation.
```

--------------------------------

### Make an authenticated API request

Source: https://docs.gummble.com/docs/quickstart

Use curl to fetch a list of apps. Replace $TOKEN with your retrieved access token.

```bash
curl https://api.gummble.com/api/v1/apps?limit=3 \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Prompting for SaaS dashboard empty states

Source: https://docs.gummble.com/docs/mcp/v0

Use this prompt to generate a compact React layout based on SaaS dashboard empty state patterns.

```text
Use Gummble MCP to find SaaS dashboard empty states and generate a
compact React layout that borrows the strongest patterns. Include the
app references in your reasoning.
```

--------------------------------

### List Gummble MCP tools via Cursor CLI

Source: https://docs.gummble.com/docs/mcp/cursor

Verify that Cursor can discover the exact tool inventory by listing the available tools.

```bash
agent mcp list-tools gummble
```

--------------------------------

### Research prompt for paywall comparison

Source: https://docs.gummble.com/docs/mcp/bolt

Use this prompt with Gummble to compare shipped mobile subscription paywalls that explain annual value clearly. It asks for three source links and a hierarchy checklist, then instructs to build the paywall without copying any one product.

```text
Use Gummble to compare shipped mobile subscription paywalls that explain
annual value clearly. Return three source links and a short hierarchy
checklist, then build the paywall without copying any one product.
```

--------------------------------

### Prompting for mobile subscription paywalls

Source: https://docs.gummble.com/docs/mcp/v0

Use this prompt to compare mobile subscription paywalls and build a responsive section with similar hierarchy.

```text
Use Gummble MCP to compare mobile subscription paywalls with annual
savings callouts, then build a responsive paywall section with similar
information hierarchy.
```

--------------------------------

### Fetch Authorization Server Metadata

Source: https://docs.gummble.com/docs/mcp/build-integration

Retrieve the OAuth endpoints from the authorization server.

```bash
curl https://api.gummble.com/.well-known/oauth-authorization-server
```

--------------------------------

### PKCE Authorization Flow

Source: https://docs.gummble.com/docs/authentication

A sequence of cURL commands demonstrating the OAuth 2.1 PKCE flow, including server discovery, dynamic client registration, authorization URL construction, and token exchange.

```bash
# 1. Discover
curl https://api.gummble.com/.well-known/oauth-authorization-server | jq

# 2. Register a client
curl -X POST https://api.gummble.com/oauth/register \
  -H 'content-type: application/json' \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["http://127.0.0.1:8080/callback"],
    "application_type": "native",
    "token_endpoint_auth_method": "none"
  }'

# 3. Build the authorize URL
#    response_type=code & client_id & redirect_uri & state
#    & code_challenge(S256) & code_challenge_method=S256
#    & resource=https://mcp.gummble.com/mcp (RFC 8707)

# 4. Exchange code for tokens
curl -X POST https://api.gummble.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=..." \
  -d "client_id=..." \
  -d "redirect_uri=..." \
  -d "code_verifier=..." \
  -d "resource=https://mcp.gummble.com/mcp"
```

--------------------------------

### Download screen endpoint

Source: https://docs.gummble.com/docs/api/screens

Returns a short-lived signed URL for the screen image. Requires a pro or team plan.

```http
GET /api/v1/screens/:id/download
```

--------------------------------

### Bulk Download with Rate Limit Awareness

Source: https://docs.gummble.com/docs/cookbook

Uses p-limit to throttle concurrent downloads to 4, staying under the backoff tier. Requires the downloadOne function to be implemented.

```typescript
import pLimit from 'p-limit'
const concurrency = pLimit(4)         // stay under the backoff tier

async function downloadAll(screenIds: string[], token: string) {
  await Promise.all(
    screenIds.map(id =>
      concurrency(() => downloadOne(id, token))
    )
  )
}
```

--------------------------------

### Initialize MCP authentication

Source: https://docs.gummble.com/docs/mcp/claude-code

Initiates the authentication flow for registered MCP servers within an active Claude Code session.

```bash
/mcp
```

--------------------------------

### Register Application via Dynamic Client Registration

Source: https://docs.gummble.com/docs/mcp/build-integration

Register the application to obtain a client_id. Gummble MCP clients are public and do not use a client_secret.

```bash
curl -X POST https://api.gummble.com/oauth/register \
  -H "content-type: application/json" \
  -d '{
    "client_name": "Example App",
    "redirect_uris": ["https://example.com/oauth/gummble/callback"],
    "application_type": "web",
    "token_endpoint_auth_method": "none",
    "scope": "mcp:read mcp:tools"
  }'
```

--------------------------------

### Visual search POST request

Source: https://docs.gummble.com/docs/api/search

Initiate a visual search by uploading an image to find similar screens.

```http
POST /api/v1/search/visual
Content-Type: multipart/form-data
```

--------------------------------

### Add Gummble MCP server via Copilot CLI

Source: https://docs.gummble.com/docs/mcp/github-copilot

Adds the user-scoped remote HTTP server using the copilot mcp add command.

```bash
copilot mcp add --transport http gummble https://mcp.gummble.com/mcp
```

--------------------------------

### POST /api/v1/search/visual

Source: https://docs.gummble.com/docs/api/search

Uploads an image and returns the top-K visually similar screens by embedding cosine similarity. Validates uploads by magic-byte sniffing and accepts only JPEG, PNG, and WebP under 8 MiB.

```APIDOC
## POST /api/v1/search/visual

### Description
Uploads an image and returns the top-K visually similar screens by embedding cosine similarity. Validates uploads by magic-byte sniffing and accepts only JPEG, PNG, and WebP under 8 MiB.

### Method
POST

### Endpoint
/api/v1/search/visual

### Parameters
#### Request Body (multipart/form-data)
- **image** (file) - Required - Image file (JPEG, PNG, WebP, under 8 MiB)
- **limit** (number) - Optional - Max results (default 10, max 50)

### Request Example
curl -X POST https://api.gummble.com/api/v1/search/visual \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@screenshot.png" \
  -F "limit=10"

### Response
#### Success Response (200)
- **data** (array) - List of search results
- **type** (string) - Result type (e.g., screen)
- **score** (number) - Similarity score (0-1)
- **item** (object) - Full Screen object

#### Response Example
{
  "data": [
    {
      "type": "screen",
      "score": 0.87,
      "item": { ... full Screen object ... }
    }
  ]
}
```

--------------------------------

### VS Code mcp.json configuration

Source: https://docs.gummble.com/docs/mcp/github-copilot

Adds Gummble as an HTTP server in .vscode/mcp.json. Use the Auth action for OAuth; do not hardcode secrets.

```json
{
  "servers": {
    "gummble": {
      "type": "http",
      "url": "https://mcp.gummble.com/mcp"
    }
  }
}
```

--------------------------------

### Fetch Protected Resource Metadata

Source: https://docs.gummble.com/docs/mcp/build-integration

Retrieve the authorization server and supported scopes for the Gummble protected resource.

```bash
curl https://mcp.gummble.com/.well-known/oauth-protected-resource/mcp
```

--------------------------------

### Add Gummble MCP server to Codex

Source: https://docs.gummble.com/docs/mcp/codex

Run this command to add the Gummble MCP server. Codex will automatically detect OAuth support and prompt for browser-based authentication.

```bash
codex mcp add gummble --url https://mcp.gummble.com/mcp
```

--------------------------------

### Gummble MCP project or global config

Source: https://docs.gummble.com/docs/mcp/kilo-code

JSON configuration for a project (`./kilo.json` or `./.kilo/kilo.json`) or global (`~/.config/kilo/kilo.json`). Gummble supports Dynamic Client Registration, so no static client ID, secret, API key, or bearer token belongs in the file. Project config takes precedence over global.

```json
{
  "mcp": {
    "gummble": {
      "type": "remote",
      "url": "https://mcp.gummble.com/mcp",
      "enabled": true,
      "timeout": 15000
    }
  }
}
```

--------------------------------

### Configure Windsurf MCP for Gummble

Source: https://docs.gummble.com/

Add the Gummble MCP server to your Windsurf configuration to enable direct library access.

```json
# Windsurf MCP config
{
  "mcpServers": {
    "gummble": {
      "serverUrl": "https://mcp.gummble.com/mcp"
    }
  }
}
```

--------------------------------

### Verify MCP tool functionality

Source: https://docs.gummble.com/docs/mcp/claude-code

A sample prompt to test if Claude Code can successfully invoke Gummble MCP tools for UI research.

```text
Use Gummble MCP to find 5 mobile onboarding screens from language
learning apps and compare their first-step layouts.
```

--------------------------------

### Add Gummble MCP server to mcp.json

Source: https://docs.gummble.com/docs/mcp/cursor

Manual configuration for Cursor's MCP settings. Add this entry to ~/.cursor/mcp.json for all projects or .cursor/mcp.json for a single project. The URL is the remote MCP endpoint.

```json
{
  "mcpServers": {
    "gummble": {
      "url": "https://mcp.gummble.com/mcp"
    }
  }
}
```

--------------------------------

### Verify MCP server connection

Source: https://docs.gummble.com/docs/mcp/codex

Use this command to list connected MCP servers and confirm that gummble is logged in.

```bash
codex mcp list
```

--------------------------------

### Manual configuration for Codex

Source: https://docs.gummble.com/docs/mcp/codex

Add this configuration to your ~/.codex/config.toml or project-level .codex/config.toml file to manually define the Gummble server.

```toml
[mcp_servers.gummble]
url = "https://mcp.gummble.com/mcp"
```

--------------------------------

### Redirect User for Authorization with PKCE

Source: https://docs.gummble.com/docs/mcp/build-integration

Redirect the user to the authorization endpoint using a PKCE verifier and S256 challenge.

```http
https://api.gummble.com/oauth/authorize?
  response_type=code&
  client_id=<client_id>&
  redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fgummble%2Fcallback&
  state=<random_state>&
  code_challenge=<s256_challenge>&
  code_challenge_method=S256&
  resource=https%3A%2F%2Fmcp.gummble.com%2Fmcp&
  scope=mcp%3Aread%20mcp%3Atools
```

--------------------------------

### Authorize Gummble MCP manually

Source: https://docs.gummble.com/docs/mcp/codex

After adding the manual configuration, run this command to perform the one-time authorization.

```bash
codex mcp login gummble
```

--------------------------------

### Prompt Lovable to use Gummble for empty state research

Source: https://docs.gummble.com/docs/mcp/lovable

Use this prompt to instruct the Lovable Agent to research real SaaS empty states via Gummble, compare first-use guidance, recovery actions, and permission states, and cite source links before building the page.

```text
Use Gummble to find real SaaS empty states for a new project with no
imported data. Compare first-use guidance, recovery actions, and permission
states. Cite the Gummble source links, then build the page.
```

--------------------------------

### Prompt Lovable to use Gummble for paywall research

Source: https://docs.gummble.com/docs/mcp/lovable

Use this prompt to instruct the Lovable Agent to compare mobile subscription paywalls with annual savings, trial disclosure, and restore-purchase actions via Gummble, summarize the strongest information hierarchy with source links, and implement a responsive paywall without copying any one product.

```text
Use Gummble to compare mobile subscription paywalls with annual savings,
trial disclosure, and restore-purchase actions. Summarize the strongest
information hierarchy with source links, then implement a responsive
paywall without copying any one product.
```

--------------------------------

### Authenticate Gummble MCP in Copilot CLI

Source: https://docs.gummble.com/docs/mcp/github-copilot

Run this command in Copilot CLI when Gummble reports needs-auth to complete the browser OAuth flow.

```text
/mcp auth gummble
```

--------------------------------

### Authenticate Gummble MCP via Cursor CLI

Source: https://docs.gummble.com/docs/mcp/cursor

Use this command to authenticate the configured Gummble server when using Cursor's CLI.

```bash
agent mcp login gummble
```

--------------------------------

### Visual Search from Clipboard Image

Source: https://docs.gummble.com/docs/cookbook

Reads an image from the clipboard and posts it to the visual search endpoint with a limit of 12. Throws an error if no image is in the clipboard.

```typescript
async function searchFromClipboard(token: string) {
  const items = await navigator.clipboard.read()
  const item = items.find(i => i.types.some(t => t.startsWith('image/')))
  if (!item) throw new Error('No image in clipboard')
  const type = item.types.find(t => t.startsWith('image/'))!
  const blob = await item.getType(type)

  const form = new FormData()
  form.set('image', blob, 'clipboard.png')
  form.set('limit', '12')

  const res = await fetch(
    'https://api.gummble.com/api/v1/search/visual',
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}` },
      body: form,
    }
  )
  return res.json()
}
```

--------------------------------

### List apps endpoint

Source: https://docs.gummble.com/docs/api/apps

Lists apps in the Gummble library. Supports query parameters for search, filtering, pagination, and platform selection.

```http
GET /api/v1/apps
```

--------------------------------

### Verify Gummble MCP server and OAuth state

Source: https://docs.gummble.com/docs/mcp/kilo-code

Lists configured servers and OAuth state. Use `kilo mcp debug gummble` only when the connection needs diagnosis; redact OAuth metadata before sharing debug output.

```bash
kilo mcp list
kilo mcp auth list
```

--------------------------------

### Legacy SSE-only endpoint

Source: https://docs.gummble.com/docs/mcp/troubleshooting

The fallback endpoint for legacy clients that only support SSE.

```text
https://mcp.gummble.com/sse
```

--------------------------------

### Verify Webhook Signature

Source: https://docs.gummble.com/docs/webhooks

Code snippet demonstrating how to verify the X-Gummble-Signature header using HMAC SHA256 and timing-safe comparison.

```APIDOC
## Verify Webhook Signature

### Description
Verifies the signature of an incoming webhook delivery to ensure it originated from Gummble and is not a replay.

### Method
N/A (SDK/Code snippet)

### Endpoint
N/A

### Parameters
- **secret** (string) - Required - The webhook secret used to sign deliveries.
- **header** (string) - Required - The value of the `X-Gummble-Signature` header.
- **rawBody** (string) - Required - The raw request body.

### Request Example
```javascript
function verify(secret, header, rawBody) {
  const [t, v1] = header.split(',').map(p => p.split('=')[1])
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  // timing-safe compare
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
    && (Date.now()/1000 - Number(t) < 300)
}
```

### Response
#### Success Response (200)
- **boolean** (boolean) - Returns `true` if the signature is valid and the timestamp is within 5 minutes, otherwise `false`.

#### Response Example
```json
true
```
```

--------------------------------

### Add Gummble MCP server configuration

Source: https://docs.gummble.com/docs/mcp/kiro

Add this JSON to your Kiro MCP configuration file (workspace or user) to register the Gummble remote server. Keep autoApprove empty while reviewing tool behavior.

```json
{
  "mcpServers": {
    "gummble": {
      "url": "https://mcp.gummble.com/mcp",
      "disabled": false,
      "autoApprove": [],
      "disabledTools": []
    }
  }
}
```

--------------------------------

### Configure Gummble MCP in mcp_config.json

Source: https://docs.gummble.com/docs/mcp/windsurf

Add the Gummble server URL to the mcpServers object in your Windsurf MCP configuration file.

```json
{
  "mcpServers": {
    "gummble": {
      "serverUrl": "https://mcp.gummble.com/mcp"
    }
  }
}
```

--------------------------------

### Exchange Authorization Code for Tokens

Source: https://docs.gummble.com/docs/mcp/build-integration

Exchange the authorization code for an access token and refresh token using the PKCE verifier.

```bash
curl -X POST https://api.gummble.com/oauth/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<client_id>" \
  -d "code=<authorization_code>" \
  -d "redirect_uri=https://example.com/oauth/gummble/callback" \
  -d "code_verifier=<pkce_verifier>" \
  -d "resource=https://mcp.gummble.com/mcp"
```

--------------------------------

### Call MCP Server

Source: https://docs.gummble.com/docs/mcp/build-integration

Send a JSON-RPC request to the MCP server using the access token.

```bash
curl -X POST https://mcp.gummble.com/mcp \
  -H "authorization: Bearer <access_token>" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

--------------------------------

### List screens endpoint

Source: https://docs.gummble.com/docs/api/screens

Retrieves a list of screens, supporting filters for appId, UI pattern, dominant colors, and free-text search.

```http
GET /api/v1/screens
```

--------------------------------

### OAuth Request Sequence

Source: https://docs.gummble.com/docs/mcp/oauth

The complete OAuth flow MCP clients must follow, from initial POST to token refresh. Steps 1-7 cover authorization and token exchange, step 8 handles refresh token rotation. Includes exact endpoints, parameters, and responses.

```text
1.  POST  https://mcp.gummble.com/mcp
            (no Authorization)
    ←   401 + WWW-Authenticate: Bearer realm="mcp",
              resource_metadata="https://mcp.gummble.com/.well-known/oauth-protected-resource/mcp"

2.  GET   https://mcp.gummble.com/.well-known/oauth-protected-resource/mcp
    ←   { authorization_servers: ["https://api.gummble.com"], ... }

3.  GET   https://api.gummble.com/.well-known/oauth-authorization-server
    ←   { authorization_endpoint, token_endpoint, registration_endpoint,
            jwks_uri, code_challenge_methods_supported: ["S256"], ... }

4.  POST  https://api.gummble.com/oauth/register
            { client_name, redirect_uris, application_type, ... }
    ←   201 { client_id, redirect_uris, ... }

5.  Browser → https://api.gummble.com/oauth/authorize?
            response_type=code & client_id & redirect_uri & state
            & code_challenge & code_challenge_method=S256
            & resource=https://mcp.gummble.com/mcp
    ←   302 → https://gummble.com/login?return_to=…
    (user signs in)
    ←   302 → http://127.0.0.1:PORT/callback?code=…&state=…

6.  POST  https://api.gummble.com/oauth/token
            grant_type=authorization_code & code & client_id
            & redirect_uri & code_verifier
            & resource=https://mcp.gummble.com/mcp
    ←   200 { access_token, refresh_token, token_type, expires_in }

7.  POST  https://mcp.gummble.com/mcp
            Authorization: Bearer <access_token>
    ←   200 (MCP JSON-RPC)

   When access_token expires:
8.  POST  https://api.gummble.com/oauth/token
            grant_type=refresh_token & refresh_token & client_id
            & resource=https://mcp.gummble.com/mcp
    ←   200 { access_token, refresh_token (rotated), ... }
```

--------------------------------

### List flows

Source: https://docs.gummble.com/docs/api/flows

Lists flows. Supports query parameters: appId (filter by app), type (flow type like onboarding, paywall, checkout), and platform (IOS, ANDROID, WEB; lowercase tokens accepted and normalized).

```http
GET /api/v1/flows
```

--------------------------------

### POST /oauth/register

Source: https://docs.gummble.com/docs/authentication

Dynamically registers an OAuth client (RFC 7591). This endpoint allows clients to register themselves and obtain a client_id and client_secret if needed.

```APIDOC
## POST /oauth/register

### Description
Dynamically registers an OAuth client (RFC 7591). This endpoint allows clients to register themselves and obtain a client_id and client_secret if needed.

### Method
POST

### Endpoint
https://api.gummble.com/oauth/register

### Parameters
#### Request Body
- **client_name** (string) - Required - The name of the client application.
- **redirect_uris** (array of strings) - Required - List of redirect URIs for the client.
- **application_type** (string) - Optional - The type of application (e.g., "native", "web").
- **token_endpoint_auth_method** (string) - Optional - The authentication method for the token endpoint (e.g., "none", "client_secret_basic").

### Request Example
{
  "client_name": "My App",
  "redirect_uris": ["http://127.0.0.1:8080/callback"],
  "application_type": "native",
  "token_endpoint_auth_method": "none"
}

### Response
#### Success Response (201)
- **client_id** (string) - The client identifier.
- **client_secret** (string) - The client secret (if applicable).
- **client_id_issued_at** (integer) - Time at which the client was issued.
- **client_secret_expires_at** (integer) - Expiration time of the client secret.

#### Response Example
{
  "client_id": "...",
  "client_secret": "...",
  "client_id_issued_at": 1700000000,
  "client_secret_expires_at": 0
}
```

--------------------------------

### Refresh Access Token

Source: https://docs.gummble.com/docs/mcp/build-integration

Obtain a new access token using the refresh token. Note that refresh tokens rotate on every use.

```bash
curl -X POST https://api.gummble.com/oauth/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=<client_id>" \
  -d "refresh_token=<refresh_token>" \
  -d "resource=https://mcp.gummble.com/mcp"
```

--------------------------------

### Verify webhook signature in Node.js

Source: https://docs.gummble.com/docs/webhooks

A function to verify the webhook signature using a timing-safe comparison and check for replay protection by ensuring the timestamp is within 5 minutes.

```javascript
function verify(secret, header, rawBody) {
  const [t, v1] = header.split(',').map(p => p.split('=')[1])
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  // timing-safe compare
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
    && (Date.now()/1000 - Number(t) < 300)
}
```