Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt

Use this file to discover all available pages before exploring further.

POST /v1/ai-visibility/:appId/bootstrap
Bootstrap is the one-time setup call that turns AI Visibility on for an app. It runs three things in sequence:
  1. Reads your app metadata (title, subtitle, description, primary genre) and a sample of the keywords you already rank for.
  2. Generates intents — 8–12 user goals your app addresses, written in the language a real user would use when asking an AI assistant.
  3. Generates prompts per intent — 5–8 user-style queries spread across different styles (problem-led, branded, comparison, …).
  4. Queues the first scan automatically so fresh data appears within ~10 minutes.
After bootstrap finishes, the app is on autopilot — daily scheduled scans take over.
Bootstrap is idempotent. Re-running it later (after editing your app’s title, for example) only adds new intents the LLM proposes — it never deletes intents you’ve edited or added manually.

​
Path parameters

NameTypeRequiredDescription
appIdstringYesApple App ID (numeric)

​
Body

{
  "country": "us",
  "language": "en"
}
FieldTypeDefaultDescription
countrystringusISO country code — biases the LLM toward apps available in that storefront.
languagestringenISO 639-1 language code — used as a hint for prompt phrasing.

​
Response

{
  "data": {
    "taskRunId": "run_a1b2c3d4..."
  }
}
taskRunId is the durable Trigger.dev run id; you can ignore it for normal use. The endpoint returns immediately (HTTP 201) and the work continues in the background.

​
What happens after the call

The background task takes about 3–8 minutes end-to-end:
PhaseTypical duration
Pull app metadata + keyword sample< 5s
Generate intents (LLM)5–15s
Generate prompts for each new intent (LLM, parallel)30–60s
Insert rows< 5s
Trigger first scan (scan-app-ai-visibility)runs immediately after, takes another 3–6 min for the answers + parsing to land
You can verify progress by polling the read endpoints: 
# 1. Confirm intents were generated
curl "https://api.appeeky.com/v1/ai-visibility/1234567890/intents?country=us" \
  -H "X-API-Key: YOUR_API_KEY"

# 2. After a few minutes, the overview gauge will populate
curl "https://api.appeeky.com/v1/ai-visibility/1234567890/overview?country=us&model=chatgpt" \
  -H "X-API-Key: YOUR_API_KEY"

​
When to re-run bootstrap

SituationAction
You changed the app’s title or subtitle and want the LLM to reconsider intentsRe-run bootstrap
You launched a major new feature and the LLM-generated intents are out of dateRe-run bootstrap
You just want to add a few more intentsUse POST /intents instead — much cheaper
You want to scan with the same intents but fresh AI answersUse POST /scan instead
Re-running bootstrap doesn’t disturb the prompts or answers you’ve already collected; it only inserts intents/prompts that don’t already exist.

​
Code examples

curl -X POST "https://api.appeeky.com/v1/ai-visibility/1234567890/bootstrap" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "us", "language": "en" }'

​
Credits

Bootstrap charges against your dedicated AI Visibility credit bucket — separate from your general API quota.
  • The bootstrap call itself is free (intent + prompt generation runs on Appeeky’s account, not yours).
  • The initial scan that runs immediately afterwards is metered like any other scheduled scan — see the Scan & Settings cost table. For an 8-intent × 6-prompt × 1-model (chatgpt) setup that’s ~432 credits up front.
Two safeguards before the call ever runs:
  • Tier gate: bootstrap requires the Indie plan or higher. Free-plan calls return 403 TIER_LIMIT_EXCEEDED.
  • Quota gate: when the AI Visibility bucket is empty, bootstrap returns 429 AI_VISIBILITY_QUOTA_EXCEEDED instead of queuing intents+prompts the user can’t measure.
Bootstrap is also rate-limited per app — calling it twice in the same hour is allowed but the second call usually returns the same intents (deduplicated by fingerprint) so you waste credits.

​
Errors

StatusCodeWhen
400INVALID_APP_IDMissing or non-numeric app ID
403TIER_LIMIT_EXCEEDEDCaller is on the free plan — upgrade to Indie or higher
404APP_NOT_FOUNDApp is not available in the requested country
401—Missing or invalid API key / JWT
429AI_VISIBILITY_QUOTA_EXCEEDEDOut of AI Visibility credits — upgrade or wait for the quota to reset

​
See also