Gummble

https://docs.gummble.com
Admin
Gummble is a programmable design library providing curated UI references from thousands of apps via...
Tokens:26,317
Snippets:294
Trust Score:5
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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/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 }
}
```
```

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

### 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 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
```

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

### 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.
```

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

### 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.

```

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

### 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"
```

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

### 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

```

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

### 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

```

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

### 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
```

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

### 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
```

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

### 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.
```

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

### 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)
```

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

### 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
```

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

### 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"
}
```

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

### 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
```

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

### 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 ... }
    }
  ]
}
```

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

### 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
```

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

### 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
}
```

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

### 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
```

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

### 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"]
}
```

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

### 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=...
```

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

### 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
```

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

### 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
}
```

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

### 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"
```
Tokens:
Raw