{
    "openapi": "3.1.0",
    "info": {
        "title": "Shoplist public profile discovery",
        "version": "1.0.0",
        "description": "A bounded public-read search contract for existing public profile lookup endpoints. This is not the planned paid REST API. For HTML search without JavaScript use https://shoplist.co/search?query=Judge.me. Support: hello@shoplist.co.",
        "contact": {
            "email": "hello@shoplist.co"
        }
    },
    "servers": [
        {
            "url": "https://shoplist.co"
        }
    ],
    "paths": {
        "/api/search": {
            "get": {
                "operationId": "searchPublicProfiles",
                "summary": "Search public apps, brands, and experts",
                "description": "Anonymous read-only discovery. 60 requests per minute per client IP for this endpoint, independently of the other endpoint. Successful complete responses may be shared-cacheable for five minutes with stale-while-revalidate of one day, so repeated reads may reflect a cached result. No contact reveals, account data, exports, or paid API access. Do not use this surface for bulk extraction.",
                "security": [],
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": true,
                        "description": "Name or lexical search text. Leading and trailing whitespace is trimmed.",
                        "schema": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 200
                        },
                        "example": "Judge.me"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 12,
                            "default": 6
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Public results; an empty list is a successful search with no matches.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["results", "query", "limit", "count"],
                                    "properties": {
                                        "query": {
                                            "type": "string"
                                        },
                                        "limit": {
                                            "type": "integer"
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "results": {
                                            "type": "array",
                                            "maxItems": 12,
                                            "items": {
                                                "type": "object",
                                                "required": [
                                                    "type",
                                                    "name",
                                                    "href",
                                                    "logoFileUrl",
                                                    "eyebrow",
                                                    "detail"
                                                ],
                                                "properties": {
                                                    "type": {
                                                        "type": "string",
                                                        "enum": ["app", "brand", "expert"]
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "href": {
                                                        "type": "string",
                                                        "description": "Relative public profile URL."
                                                    },
                                                    "logoFileUrl": {
                                                        "type": ["string", "null"]
                                                    },
                                                    "eyebrow": {
                                                        "type": ["string", "null"]
                                                    },
                                                    "detail": {
                                                        "type": ["string", "null"]
                                                    }
                                                }
                                            }
                                        },
                                        "unavailable_sources": {
                                            "type": "array",
                                            "items": {
                                                "type": "string",
                                                "enum": ["app", "brand", "expert"]
                                            },
                                            "description": "Present when one or more sources fail. Successful results remain available; a partial response is not shared-cacheable."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid query or limit: search:invalid-params.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate allowance exhausted: rate_limited.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying. Honor this value rather than retrying immediately.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 1
                                }
                            },
                            "X-RateLimit-Limit": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Per-client rate allowance metadata."
                            },
                            "X-RateLimit-Remaining": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Per-client rate allowance metadata."
                            },
                            "X-RateLimit-Reset": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Reset is a Unix timestamp in seconds; Remaining is zero."
                            }
                        }
                    },
                    "502": {
                        "description": "Upstream search failed: search:failed (universal) or search:apps-failed (apps).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Rate service unavailable: rate_limit_unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying. Honor this value rather than retrying immediately.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 1
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/search/apps": {
            "get": {
                "operationId": "searchPublicApps",
                "summary": "Search public Shopify app profiles",
                "description": "Anonymous read-only discovery. 60 requests per minute per client IP for this endpoint, independently of the other endpoint. Successful complete responses may be shared-cacheable for five minutes with stale-while-revalidate of one day, so repeated reads may reflect a cached result. No contact reveals, account data, exports, or paid API access. Do not use this surface for bulk extraction.",
                "security": [],
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": true,
                        "description": "Name or lexical search text. Leading and trailing whitespace is trimmed.",
                        "schema": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 200
                        },
                        "example": "Judge.me"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 20,
                            "default": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Public results; an empty list is a successful search with no matches.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["results", "query", "limit", "count"],
                                    "properties": {
                                        "query": {
                                            "type": "string"
                                        },
                                        "limit": {
                                            "type": "integer"
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "results": {
                                            "type": "array",
                                            "maxItems": 20,
                                            "items": {
                                                "type": "object",
                                                "required": [
                                                    "name",
                                                    "href",
                                                    "developerName",
                                                    "logoFileUrl",
                                                    "tagline",
                                                    "reviewCount",
                                                    "matchReason"
                                                ],
                                                "properties": {
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "href": {
                                                        "type": "string"
                                                    },
                                                    "developerName": {
                                                        "type": ["string", "null"]
                                                    },
                                                    "logoFileUrl": {
                                                        "type": ["string", "null"]
                                                    },
                                                    "tagline": {
                                                        "type": ["string", "null"]
                                                    },
                                                    "reviewCount": {
                                                        "type": ["number", "null"]
                                                    },
                                                    "matchReason": {
                                                        "type": ["string", "null"]
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid query or limit: search:invalid-params.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate allowance exhausted: rate_limited.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying. Honor this value rather than retrying immediately.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 1
                                }
                            },
                            "X-RateLimit-Limit": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Per-client rate allowance metadata."
                            },
                            "X-RateLimit-Remaining": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Per-client rate allowance metadata."
                            },
                            "X-RateLimit-Reset": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Reset is a Unix timestamp in seconds; Remaining is zero."
                            }
                        }
                    },
                    "502": {
                        "description": "Upstream search failed: search:failed (universal) or search:apps-failed (apps).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Rate service unavailable: rate_limit_unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["error"],
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "required": ["code", "message"],
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying. Honor this value rather than retrying immediately.",
                                "schema": {
                                    "type": "integer",
                                    "minimum": 1
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}