Storelift

Storelift › Guias › A API do Storelift

Camada de IA

A API do Storelift

Tudo o que o painel mostra também é um endpoint JSON. São 27 endpoints GET que leem os seus apps acompanhados e o mercado, e POST /v1/actions mostra a prévia de uma mudança que POST /v1/actions/confirm aplica em seguida — assim um script, uma rotina de planilha ou uma etapa de CI leem os mesmos números e agem sobre eles. A referência completa está em /docs/api/ e a especificação legível por máquina em /openapi.json (OpenAPI 3.1); um assistente que trabalha com os mesmos dados costuma preferir o servidor MCP, incluído a partir do Pro.

Começar grátis →Plano Free: 1 app, 10 palavras-chave em cada uma de 2 lojas, 14 dias de histórico, sem cartão e sem prazo. O Pro custa US$ 29/mês.

Por Atualizado: 10 min de leitura

Acompanhamento de palavras-chave · histórico de posições, movimentos da semana e palavras-chave acompanhadas

Endereço base e autenticação

A base é https://storelift.net/v1. Crie uma chave em Configurações → API; ela é exibida uma única vez e guardada só como hash, então uma chave perdida é substituída, não recuperada.

Envie-a como x-api-key, ou como bearer token se o seu cliente só trabalha com cabeçalhos Authorization:

Terminal
curl -s https://storelift.net/v1/apps \
  -H "x-api-key: sl_live_..."
O acesso à API está nos planos Pro e Studio — a partir de US$ 29 por mês, US$ 99 no Studio. A chave é mantida quando o plano é rebaixado, então voltar ao plano reativa a mesma integração.

Os 27 endpoints

EndpointO que retorna
GET /v1/appsOs apps que esta conta acompanha; o id das outras chamadas vem daqui.
GET /v1/apps/{id}Um app e o retrato da execução mais recente.
GET /v1/apps/{id}/keywordsA posição atual de cada palavra-chave acompanhada em um storefront, com o estado da medição e a profundidade buscada.
GET /v1/apps/{id}/rivalsOs apps que estão acima de você, cada um com os termos em que ganha de você e as duas posições.
GET /v1/apps/{id}/aiSe um assistente cita o seu app para a sua categoria, com a série armazenada. Exige Pro, Studio ou Enterprise.
GET /v1/apps/{id}/historyA série de posições por palavra-chave, cortada na janela de histórico do plano.
GET /v1/apps/{id}/pageA sua própria página como a loja a serve, nas duas plataformas, mais as mudanças datadas detectadas nela.
GET /v1/apps/{id}/reviewsAvaliações recentes com o resumo de estrelas, quantas são novas nesta execução e o lado do Play quando medido. /reviews/search busca em todo o arquivo por texto, estrelas, versão e datas; /reviews/stats traz a distribuição, a curva diária e o detalhamento por versão.
GET /v1/apps/{id}/timelineMudanças datadas da ficha — versão, capturas, eventos, destaques, alterações no campo de palavras-chave — cada uma com o movimento de posições das palavras-chave ao redor.
GET /v1/apps/{id}/featuringCartões editoriais, In-App Events e a prateleira “Você também pode gostar” da Apple por país, com o histórico datado de destaques e novos eventos.
GET /v1/apps/{id}/chartsA posição no top chart do gênero e do storefront do app, com a série.
GET /v1/apps/{id}/revenueReceita e downloads do app a partir das fontes conectadas: unidades do App Store Connect, instalações do Google Play, MRR, assinaturas e testes do RevenueCat. connected:false quando nada está conectado. Escopo revenue:read.
GET /v1/apps/{id}/subscriptionsContagem de eventos de assinatura do webhook do RevenueCat / Adapty, por dia, país e coorte mensal. Escopo revenue:read.
GET /v1/apps/{id}/funnelImpressões na App Store → visualizações da página do produto → downloads: o ponto de hoje e o histórico dia a dia das análises do App Store Connect. Escopo revenue:read.
GET /v1/apps/{id}/pricingPreços em vigor por produto e país e cada período de preço fixo com testes, primeiras assinaturas pagas e receita, além dos códigos de oferta, pelo webhook do RevenueCat / Adapty. Escopo revenue:read.
GET /v1/apps/{id}/campaignsCampanhas do Apple Ads que promovem o app (casadas pelo id da App Store): gasto, toques, instalações, orçamento e status, mais as principais palavras-chave e termos de busca. Escopo ads:read.

Os endpoints abaixo de /apps/{id} aceitam country (um código de storefront como us; o padrão é o primeiro do app) e, quando as duas lojas são medidas, platform=ios|android.

Os três estados de medição atravessam a fronteira

Um campo de posição pode ser um número, mas a ausência de número são duas coisas diferentes, e a API mantém as duas separadas:

  • measured: true, rank: 7 — o app foi encontrado na posição 7.
  • measured: true, rank: null — a busca rodou e o app não estava nos resultados até searchDepth.
  • measured: false — a busca não pôde ser feita naquele dia. Nada se sabe sobre a posição.
JSON
{
  "country": "de",
  "platform": "ios",
  "live": true,
  "measuredAt": "2026-09-19T02:14:08.921Z",
  "keywords": [
    { "term": "traumdeutung", "measured": true,  "rank": 7,    "demand": 6, "searchDepth": 200 },
    { "term": "traumsymbole", "measured": true,  "rank": null, "demand": 3, "searchDepth": 200 },
    { "term": "traumtagebuch", "measured": false, "rank": null, "demand": null, "searchDepth": null }
  ]
}

Juntar os dois últimos num zero descreveria uma queda que nunca aconteceu, e toda média construída em cima disso sairia errada. Se o seu código precisa de um único número, trate measured: false como uma lacuna na série, não como um valor.

Conta, uso e busca

Quatro endpoints sobre a própria chave e os registros da conta. Os dois primeiros não custam nada, então um script pode conferir o que pode ler e quanto resta antes de começar. search e fetch seguem o formato que o ChatGPT espera de um conector de deep research: uma consulta retorna ids, um id retorna o registro.

EndpointO que retorna
GET /v1/accountDe quem é a chave: plano, método de autenticação, escopos, apps legíveis, saldo de créditos.
GET /v1/usageCada cota com usado / limite / renovação, a cota do Hive de hoje e a taxa por segundo.
GET /v1/search?q=Busca nos seus próprios apps, palavras-chave acompanhadas e concorrentes; retorna ids para /v1/fetch.
GET /v1/fetch?id=O registro completo por trás de um id da busca: ficha do app, uma palavra-chave com histórico ou um concorrente com os termos em que ganha de você.

Hive: qualquer app, qualquer mercado

Os endpoints acima leem os seus próprios apps acompanhados. Os endpoints Hive leem o que a rede inteira mede — charts, a medição diária de qualquer app, listas de resultados de palavras-chave, as palavras-chave de um concorrente e a receita e os downloads de qualquer app. Eles exigem um escopo próprio na chave e custam mais créditos por chamada; cada plano também tem uma cota diária do Hive, para que um mês de créditos dure um mês.

EndpointO que retornaEscopo
GET /v1/hive/charts?country=&kind=&genre=A lista Top Free, Top Grossing ou iPad de um storefront (100 posições) no dia mais recente.hive:read
GET /v1/hive/apps/{storeId}?country=A medição diária mais recente de qualquer app: número de avaliações, nota, versão, preço, distribuição de estrelas, selo de categoria, além de idiomas suportados, próximos eventos no app, texto promocional e compras no app em destaque.hive:read
GET /v1/hive/keywords/{term}/ranks?country=&days=&top=Quem se posicionou para uma palavra-chave, dia a dia (1.000 linhas por chamada).hive:read
GET /v1/hive/spy/{storeId}?country=As palavras-chave em que um concorrente se posiciona — mesma cota mensal de espionagem do painel.hive:spy
GET /v1/hive/estimate/{storeId}?country=Receita e downloads mensais de qualquer app da App Store, no mundo todo (202 enquanto a primeira leitura roda).hive:estimate
GET /v1/hive/movers?country=&kind=&genre=&days=&limit=Quem subiu, quem caiu, quem entrou e quem saiu de um top chart, em relação ao mesmo chart N dias atrás. Cada variação é traçada entre dois dias medidos, e a resposta nomeia os dois.hive:read
GET /v1/hive/new?days=&country=&limit=Apps vistos num top chart pela primeira vez, dos mais novos para os mais antigos. A resposta informa quantos desses dias o índice cobre.hive:read
GET /v1/hive/find?genre=&country=&kind=&released=&rankMin=&rankMax=&text=&publisher=&page=Encontre apps nos charts que medimos: filtre por categoria, storefront, chart (Top Grossing, Top Free, Top Paid, Top iPad), faixa de posição, data da primeira aparição, nome ou publisher. Cada linha traz a receita e os downloads do app.hive:read
GET /v1/hive/gap?ids=&country=&platform=Gap de palavras-chave de até cinco apps lado a lado: em que termo cada um se posiciona e qual deixa escapar. Hive Explorer. Cada app traz o próprio estado de medição.hive:spy
GET /v1/hive/publisher/{publisherId}Todos os apps de um publisher que o Hive já viu, com o dia em que cada um entrou num chart pela primeira vez.hive:read
GET /v1/hive/resolve?q=&country=&limit=O id de qualquer app a partir de nome, desenvolvedor, link da loja, id da App Store ou nome de pacote. Os nomes passam pela busca da App Store daquela loja.hive:read
GET /v1/hive/similar/{storeId}?country=A prateleira de apps semelhantes da loja para qualquer app, na ordem da prateleira, com a categoria e o nome de cada um e o dia da leitura.hive:read
GET /v1/hive/reviews/{storeId}?country=&limit=As avaliações recentes de qualquer app em uma loja com a distribuição de estrelas; sem nomes de autores.hive:read

Nada pessoal atravessa esta linha: autores de avaliações nunca aparecem, e uma palavra-chave de um concorrente só aparece quando pelo menos duas outras contas a acompanham, ou você mesmo.

Teste sem chave

Todo caminho também existe em /v1/sandbox/, sem chave nenhuma: os mesmos formatos, um conjunto fixo de dois apps e datas que acompanham o dia de ontem. As respostas trazem x-sandbox: true. Para CI, você pode criar uma chave de teste (sl_test_) em Configurações — ela responde só a partir do sandbox, não gasta créditos e funciona em todos os planos, então uma chave de teste vazada não expõe nada.

Terminal
curl -s https://storelift.net/v1/sandbox/apps
curl -s 'https://storelift.net/v1/sandbox/hive/keywords/sleep%20sounds/ranks?country=us&days=3&top=10'

Como funcionam as escritas e os escopos

  • Toda escrita passa antes por uma prévia. POST /v1/actions retorna o diff antes/depois, o custo em créditos e um token de uso único, sem mudar nada; POST /v1/actions/confirm aplica a mudança. O token fica preso à ação, aos argumentos e ao estado do alvo no momento da prévia, então, se o alvo mudou nesse meio-tempo, a confirmação retorna confirm_token_mismatch com o novo diff e não escreve nada. As ações cobrem palavras-chave, concorrentes, apps, links de compartilhamento e respostas a avaliações (a partir do Pro) e, no Studio, o texto da página numa versão editável da App Store e pausa, retomada e orçamento diário no Apple Ads. A lista completa está na referência.
  • Os escopos de escrita são opcionais. Cada escrita exige o seu escopo (track:write, reports:write, reviews:write, ads:write, listing:write); eles vêm desmarcados quando uma chave é criada. A cobrança fica nas configurações da sua conta.
  • Confira a data e o estado da observação. A resposta pode conter uma medição preservada, ausência de dados verificada, trabalho pendente ou erro. Repetir a solicitação não atualiza uma observação antiga.
  • A camada de receita fica atrás dos próprios escopos. Os dez endpoints de crescimento (revenue, subscriptions, funnel, pricing, change-impact, campaigns, ads-keywords, ads-search-terms, ads-commands, search-popularity) respondem a uma chave criada com os escopos sensíveis revenue:read / ads:read, então uma chave só abre dados de receita quando você escolhe. O GA4 fica no painel.
  • O histórico segue o plano. history e charts usam a mesma janela do plano.

Erros

StatuserrorQuando
401missing_api_keyNenhuma chave na requisição.
401invalid_api_keyA chave é desconhecida ou foi revogada.
401account_deletedA conta por trás da chave não existe mais.
403plan_requiredO plano não inclui acesso à API.
405method_not_allowedLeituras são GET; POST é aceito em /v1/actions, /v1/actions/confirm e /v1/apps/{id}/validate-listing (o rascunho vai no corpo).
400unknown_actionO nome da ação não está no catálogo; a resposta lista as que estão.
400invalid_argumentsUm argumento está faltando ou mal formado; a resposta nomeia o campo.
409confirm_token_expiredO token tem mais de 10 minutos. Faça a prévia de novo.
409confirm_token_mismatchO alvo mudou depois da prévia; a resposta traz o novo diff.
403write_limit_reachedA escrita está fora dos limites de segurança (passo de orçamento, número de ações por dia).
403test_key_read_onlyChaves de teste nunca escrevem.
404job_not_foundNenhum job com esse id neste workspace.
403workspace_suspendedO workspace está suspenso; o suporte explica o motivo.
403ip_list_requiredEste workspace exige que toda chave tenha uma lista de IPs permitidos.
404not_foundEsse id de app não está nesta conta.
404unknown_endpointNão existe esse caminho em /v1.
402credits_exhaustedOs créditos deste mês acabaram; a resposta traz o link para o pacote de créditos.
429rate_limitedRequisições demais para esta chave; espere os segundos indicados em Retry-After.
429daily_hive_limitA cota diária do Hive do plano acabou; renova às 00:00 UTC.
404not_measuredNão há observação verificada para o aplicativo, palavra-chave ou escopo solicitado. Dados ausentes não equivalem a zero. Confira os parâmetros e a documentação vinculada para saber quais ações estão disponíveis.
400bad_query/v1/search precisa de q com 1 a 120 caracteres.
400bad_id/v1/fetch precisa de um id exatamente como /v1/search o retornou.
403asc_requiredupdate_listing precisa de uma chave do App Store Connect conectada.
403asc_roleA chave do App Store Connect precisa da função Admin ou App Manager para editar metadados.
409no_editable_versionNenhuma versão da App Store está editável; a resposta lista os estados atuais das versões.
404locale_not_foundEsse idioma de storefront não está na versão; a resposta lista os que estão.
409changed_since_previewA página mudou no App Store Connect depois da prévia; nada foi escrito.
422asc_rejectedO App Store Connect recusou a mudança; a mensagem dele está em detail.
409in_progressUma escrita para o mesmo alvo ainda está em andamento.
403ip_not_allowedA chave tem uma lista de IPs permitidos e esta requisição veio de outro lugar.
401key_leakedA chave foi encontrada num repositório público e revogada automaticamente; crie uma nova.

Todo erro é JSON com um campo error. plan_required também retorna plan, para que o cliente diga em qual plano a chave está em vez de adivinhar.

Perguntas frequentes

Existe limite de requisições?

Sim, por chave: requisições por segundo conforme o plano (429 com Retry-After), uma cota mensal de créditos exibida nos cabeçalhos x-credits-* e uma cota diária do Hive. Cada chamada também atualiza um contador de uso na chave, para você ver em Configurações se uma chave antiga ainda está em uso.

Posso usar no plano gratuito?

As chaves de produção da API começam no Pro. O sandbox sem chave e as chaves de teste funcionam em todos os planos, o servidor MCP remoto começa no Pro, as ferramentas gratuitas deste site não exigem conta nenhuma e o plano gratuito mede um app por dia.

API ou servidor MCP?

Um script quer a API: formatos fixos, uma chamada, nenhum modelo no meio. Um assistente quer o servidor MCP, porque as ferramentas trazem as próprias descrições e ele escolhe a chamada certa sem você escrever a integração. Os dois trabalham sobre as mesmas medições, e os dois escrevem pela mesma etapa de prévia e confirmação.

Veja isso para o seu próprio app

Cole o link da loja e adicione suas palavras-chave. Posição, apps acima de você e demanda são medidos todos os dias.

Plano Free: 1 app, 10 palavras-chave em cada uma de 2 lojas, 14 dias de histórico, sem cartão e sem prazo. O Pro custa US$ 29/mês.

Começar grátis →
Grupos de concorrentes · os termos que você divide com um concorrente e os que só ele tem

Leia também