App Store API

The app store data is accessible through our API for free without write access i.e. comments, and rates.

Find Apps

POST /app_find

To find applications call the app_find endpoint: https://api.frames.sh/app_find

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
page	required - number	The current page cursor for the search.
appId	optional - string or null	Application UUID
search	optional - string or null	Search term (alphanumeric and extra symbols including dash, space, and ampersand).
category	optional - string or null	application categories - delimited by pipe character | - (see the categories list below).
type	optional - string or null	Application Type (see the types list below).
compact	optional - boolean	Show fewer details (useful for quick search i.e. searchbars).
sort	optional - JSON String	Sort the list by key i.e. { ratings: -1 }

Response

200

{
  "type": "Success",
  "reason": "Retrieve Succeeded",
  "message": [
    {
      "id": "5bd9a3ab-4898-535b-93af-6c75b92023e0",
      "owner": "7e130223-c7e8-5acc-befa-f7e03c0de3ea",
      "verified": true,
      "name": "@gif composer",
      "icon": "7d52dfba-4079-55a8-b005-592ca1015bf5.png",
      "description": "Search & Share GIFs.",
      "website": "https://hypersub.withfabric.xyz/s/gif",
      "install_link": "https://hypersub.withfabric.xyz/s/gif",
      "app_link": "https://hypersub.withfabric.xyz/s/gif",
      "type": "Action",
      "categories": "Other|Art|Food|Gallery|Utilities",
      "created_at": 1722528492511,
      "updated_at": 1722528492511,
      "overallRating": 5,
      "rated": ["b437090c-8e9f-5823-a99c-181d0681a9b1"],
      "raters": 1,
      "ratings": 5
    },
    {
      "id": "b040a23e-0d9a-5de3-b236-1dbf9402ddb7",
      "owner": "7e130223-c7e8-5acc-befa-f7e03c0de3ea",
      "verified": true,
      "name": "Boink",
      "icon": "a4255042-c80b-5ebb-b011-57146f05ff78.png",
      "description": "Boink it! Keep boinking! Score!",
      "website": "https://frames.sh",
      "install_link": "https://ny-1.frames.sh/v/38873",
      "app_link": "https://ny-1.frames.sh/v/38873",
      "type": "Frame",
      "categories": "Other|Art|Gallery",
      "created_at": 1722792449765,
      "updated_at": 1722792449765,
      "rated": [
        "c81b7096-bb82-5498-870d-0aebcb7e63a2",
        "66e23bec-d223-5f38-b11c-a2ad051b3345",
        "25be5cba-ed02-5a4d-bf37-80f8f0dbadaf"
      ],
      "raters": 3,
      "ratings": 5,
      "overallRating": 15
    },
    ...
  ]
}

400

{
  "type": "Failure",
  "reason": "Retrieve Failed",
  "message": "An error has occured while finding app."
}

Example Request - Find Apps of each type

fetch("https://api.frames.sh/app_find", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
      page: 0,
      type: "All"
    })
}).then(async r => {
    if(r.status !== 200){
        const error = await r.text();
        throw error;
    }
    return r.json();
}).then(r => {
    if(r.type === "Failure"){
        throw r.reason;
    }
    return r.message;
}).catch(e => {
    return Error(e);
});

Example Request - Find App with ID

fetch("https://api.frames.sh/app_find", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
      page: 0,
      id: "728d3910-3fca-453f-8958-dc7c71db7ffc"
    })
}).then(async r => {
    if(r.status !== 200){
        const error = await r.text();
        throw error;
    }
    return r.json();
}).then(r => {
    if(r.type === "Failure"){
        throw r.reason;
    }
    return r.message;
}).catch(e => {
    return Error(e);
});

Example Request - Find App by Categories, sorted by ratings

fetch("https://api.frames.sh/app_find", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
      page: 0,
      category: "Other|Art|Music|NFT",
      sort: JSON.stringify({ ratings: -1 })
    })
}).then(async r => {
    if(r.status !== 200){
        const error = await r.text();
        throw error;
    }
    return r.json();
}).then(r => {
    if(r.type === "Failure"){
        throw r.reason;
    }
    return r.message;
}).catch(e => {
    return Error(e);
});

Categories List

Below is the list of available categories for applications. Applications may have one or more categories. Categories are combined using the pipe character i.e. Other|Art|Music|NFT

export const applicationCategories = [
  'Other',
  'Art',
  'Music',
  'News',
  'Books',
  'Podcast',
  'Finance',
  'Food',
  'Crypto',
  'Blockchain',
  'Tipping',
  'Blog',
  'NFT',
  'Photography',
  'Software Development',
  'History',
  'Animals',
  'Games',
  'Polls & Surveys',
  'Trivia',
  'Gallery',
  'Jobs',
  'Food',
  'Analytics',
  'Utilities',
];

Types List

Applications will have a unique type, it can be a frame, action, client, or other. Below is the list of available types for applications. Overview and All are token application types to indicate searching of all types of apps.

export const applicationTypes = ['Overview', 'All', 'Frame', 'Action', 'Client', 'Other'];

Pagination

The Page cursor for searches that are not of application type Overview or All are limited to 9 per page. Otherwise, the result will contain 9 apps for each non-token application types (Frame, Action, Client, and Other).

Accessing App Icons

App icon filenames are embedded in the search results with the icon key. To access the app icons, pull the image at: https://api.frames.sh/public i.e.:

https://api.frames.sh/public/e5fc49df-18e7-5cc0-8434-fd769360a746.png

Accessing App Thumbnails

App thumbnails are automatically pulled based on the app link's OG image or frame image and are hosted at https://proxy.frames.sh.

To access the app thumbnail, use the applications app_link and remove the symbols in URI for the GET request i.e.: to retrieve https://moxie.xyz's app thumbnail use:

https://proxy.frames.sh/index/httpsmoxiexyz.png

An app may or may not have a thumbnail depending on the app link's content - OG images are fetched and used as thumbnails.

Rate Limits

The current rate limit for find requests is currently set at 256 requests per 30 seconds. This rate limit is subject to change in the future.

Questions?

Let us know on [e-mail].