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:
curl -s https://storelift.net/v1/apps \
-H "x-api-key: sl_live_..."Os 27 endpoints
| Endpoint | O que retorna |
|---|---|
GET /v1/apps | Os apps que esta conta acompanha; o id das outras chamadas vem daqui. |
GET | Um app e o retrato da execução mais recente. |
GET | A posição atual de cada palavra-chave acompanhada em um storefront, com o estado da medição e a profundidade buscada. |
GET | Os apps que estão acima de você, cada um com os termos em que ganha de você e as duas posições. |
GET | Se um assistente cita o seu app para a sua categoria, com a série armazenada. Exige Pro, Studio ou Enterprise. |
GET | A série de posições por palavra-chave, cortada na janela de histórico do plano. |
GET | A sua própria página como a loja a serve, nas duas plataformas, mais as mudanças datadas detectadas nela. |
GET | Avaliaçõ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 | Mudanç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 | Cartõ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 | A posição no top chart do gênero e do storefront do app, com a série. |
GET | Receita 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 | Contagem de eventos de assinatura do webhook do RevenueCat / Adapty, por dia, país e coorte mensal. Escopo revenue:read. |
GET | Impressõ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 | Preç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 | Campanhas 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.
{
"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.
| Endpoint | O que retorna |
|---|---|
GET /v1/account | De quem é a chave: plano, método de autenticação, escopos, apps legíveis, saldo de créditos. |
GET /v1/usage | Cada cota com usado / limite / renovação, a cota do Hive de hoje e a taxa por segundo. |
GET | Busca nos seus próprios apps, palavras-chave acompanhadas e concorrentes; retorna ids para /v1/fetch. |
GET | 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.
| Endpoint | O que retorna | Escopo |
|---|---|---|
GET | A lista Top Free, Top Grossing ou iPad de um storefront (100 posições) no dia mais recente. | hive:read |
GET | 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 | Quem se posicionou para uma palavra-chave, dia a dia (1.000 linhas por chamada). | hive:read |
GET | As palavras-chave em que um concorrente se posiciona — mesma cota mensal de espionagem do painel. | hive:spy |
GET | Receita e downloads mensais de qualquer app da App Store, no mundo todo (202 enquanto a primeira leitura roda). | hive:estimate |
GET | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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.
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/actionsretorna o diff antes/depois, o custo em créditos e um token de uso único, sem mudar nada;POST /v1/actions/confirmaplica 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 retornaconfirm_token_mismatchcom 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íveisrevenue: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.
historyechartsusam a mesma janela do plano.
Erros
| Status | error | Quando |
|---|---|---|
| 401 | missing_api_key | Nenhuma chave na requisição. |
| 401 | invalid_api_key | A chave é desconhecida ou foi revogada. |
| 401 | account_deleted | A conta por trás da chave não existe mais. |
| 403 | plan_required | O plano não inclui acesso à API. |
| 405 | method_not_allowed | Leituras são GET; POST é aceito em /v1/actions, /v1 e /v1 (o rascunho vai no corpo). |
| 400 | unknown_action | O nome da ação não está no catálogo; a resposta lista as que estão. |
| 400 | invalid_arguments | Um argumento está faltando ou mal formado; a resposta nomeia o campo. |
| 409 | confirm_token_expired | O token tem mais de 10 minutos. Faça a prévia de novo. |
| 409 | confirm_token_mismatch | O alvo mudou depois da prévia; a resposta traz o novo diff. |
| 403 | write_limit_reached | A escrita está fora dos limites de segurança (passo de orçamento, número de ações por dia). |
| 403 | test_key_read_only | Chaves de teste nunca escrevem. |
| 404 | job_not_found | Nenhum job com esse id neste workspace. |
| 403 | workspace_suspended | O workspace está suspenso; o suporte explica o motivo. |
| 403 | ip_list_required | Este workspace exige que toda chave tenha uma lista de IPs permitidos. |
| 404 | not_found | Esse id de app não está nesta conta. |
| 404 | unknown_endpoint | Não existe esse caminho em /v1. |
| 402 | credits_exhausted | Os créditos deste mês acabaram; a resposta traz o link para o pacote de créditos. |
| 429 | rate_limited | Requisições demais para esta chave; espere os segundos indicados em Retry-After. |
| 429 | daily_hive_limit | A cota diária do Hive do plano acabou; renova às 00:00 UTC. |
| 404 | not_measured | Nã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. |
| 400 | bad_query | /v1/search precisa de q com 1 a 120 caracteres. |
| 400 | bad_id | /v1/fetch precisa de um id exatamente como /v1/search o retornou. |
| 403 | asc_required | update_listing precisa de uma chave do App Store Connect conectada. |
| 403 | asc_role | A chave do App Store Connect precisa da função Admin ou App Manager para editar metadados. |
| 409 | no_editable_version | Nenhuma versão da App Store está editável; a resposta lista os estados atuais das versões. |
| 404 | locale_not_found | Esse idioma de storefront não está na versão; a resposta lista os que estão. |
| 409 | changed_since_preview | A página mudou no App Store Connect depois da prévia; nada foi escrito. |
| 422 | asc_rejected | O App Store Connect recusou a mudança; a mensagem dele está em detail. |
| 409 | in_progress | Uma escrita para o mesmo alvo ainda está em andamento. |
| 403 | ip_not_allowed | A chave tem uma lista de IPs permitidos e esta requisição veio de outro lugar. |
| 401 | key_leaked | A 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 →
