---
title: "Search screens with natural language"
method: POST
path: "/v1/screens/search"
tags: ["Screens"]
---

# Search screens with natural language

`POST /v1/screens/search`

Search Mobbin for screens using natural language. Returns relevant screens with image URLs, app names, and links to Mobbin.

## Request body

- object
  - `query` string, required — Describe one screen in plain language — the UI elements you'd see and how they relate. Be specific; detail helps. Good: "login screen with biometric authentication", "checkout page with promo code field and Apple Pay button". Avoid: combining multiple screens/intents (search separately), negations ("without ads"), vague style words ("modern", "clean"), disconnected keyword lists. Name a specific app to filter results to it (e.g. "Spotify now-playing screen"). Do not include platform (ios/web) — use the dedicated parameter.
  - `platform` 'ios' | 'web', required — Platform to search
  - `mode` 'deep' | 'standard' | 'fast' — Search mode. "standard" returns results with low latency. "deep" uses an AI-powered pipeline that interprets intent and scores results for relevance — ideal for nuanced queries. "fast" is a deprecated alias for "standard" and will be removed in a future version — use "standard" instead.
  - `limit` integer — Maximum number of screens to return
  - `image_quality` 'optimized' | 'high' — "optimized" returns images sized for AI agents and most programmatic inspection. "high" returns larger images for detailed visual inspection.
  - `exclude_screen_ids` string[] — Screen IDs to exclude from results

## Response `200`

Search results

- object
  - `screens` Screen[], required
    - `id` string, uuid, required — Unique identifier for the screen
    - `image_url` string, uri, required — Deprecated. Use `image.url` instead.
    - `image` ScreenImage, required
      - `url` string, uri, required — Image URL for the screen.
      - `width` integer — Exact width of the delivered image in pixels. Present together with `height`; both may be absent when source dimensions are unknown.
      - `height` integer — Exact height of the delivered image in pixels. Present together with `width`; both may be absent when source dimensions are unknown.
      - `url_expires_at` string, date-time, required — RFC 3339 timestamp when the image URL expires.
    - `mobbin_url` string, uri, required — Link to view this screen on Mobbin
    - `app_name` string, required — Name of the app this screen belongs to
    - `platform` 'ios' | 'web', required — Platform of the app

## Other responses

- `400` — Invalid request parameters
- `401` — Missing or invalid API key
- `403` — Team or Enterprise plan required
- `404` — Not found
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.dev/mobbin/apis/mobbin-api.md) · [All operations](https://skmtc.dev/mobbin/apis/mobbin-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mobbin/mobbin-api/revisions/9f70d096bb8e/schema)