# Preview a starter board

Preview a curated niche or find potential competitors for a selected app.

## Contract status

Preview contract: these routes and tools are implemented in the shared contract, but the public host, customer API access and OAuth flow have not been deployment verified.

## Endpoint: GET /v1/starter-boards/{nicheKey}

- Method: `GET`
- Path: `/v1/starter-boards/{nicheKey}`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `starter_boards`
- MCP action: `detail`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `nicheKey` | path | string | yes | Curated niche key, or app-<numericStoreId> to seed a preview with that stored iOS app and up to five potential competitors. |

## Known errors

- 400 invalid_request for an invalid filter, identity or limit.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing scope or unavailable preview access.
- 403 workspace_not_accessible when x-genviral-tenancy names a workspace the credential cannot reach.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.
- 429 daily_call_limit; the plan's daily API and MCP calls are used until 00:00 UTC.

## Request

No query or body. Use a curated key such as `calorie-tracking`, or `app-<numericStoreId>` for an app returned by starter-board search. The app is first, followed by up to five distinct stored iOS candidates ranked from shared keyword searches, listing names, descriptions and category. Sparse evidence produces a smaller preview. Unknown keys or apps return 404 `not_found`.

```
curl --get 'https://api.peekpanda.com/v1/starter-boards/calorie-tracking' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal'
```

## MCP request

Call starter_boards with action detail. Path fields go in params, filters in query, and a write body in body.

```
{
  "name": "starter_boards",
  "arguments": {
    "request": {
      "action": "detail",
      "params": {
        "nicheKey": "<nicheKey>"
      }
    }
  }
}

```

## Response

The preview includes at most two paid ads per app, five keywords per app and three organic posts total, plus total and locked counts. App previews also return `seed.storeId`, ordered `seed.matches` with match reasons and nullable shared-search counts, and `seed.previewToken` for adoption. Curated previews return `seed: null`. The example below is illustrative only, not a live observation.

```
{
  "key": "calorie-tracking",
  "label": "Calorie tracking",
  "seed": null,
  "apps": [],
  "organicPosts": [],
  "organicPostsTotal": 0,
  "organicPostsLocked": 0
}

```

## Source

Curated PeekPanda starter-board catalogue and public competitor evidence. No private customer board content is returned.

## Refresh

Reads stored listing, paid-ad, keyword and organic observations only. These requests never start provider collection. Each observed stream carries its observation date; missing evidence remains null or an empty list.

## Preview bounds

The lists are deliberately bounded for onboarding. Locked counts describe additional stored public evidence when available. Null counts mean the source has not been observed; zero means no matching records are available in the stored projection, without claiming complete provider coverage.

## Potential competitors

Match reasons are `shared_searches`, `similar_listing`, `similar_description` or `same_category`. Category is a weaker match, not proof of direct competition. Preserve the returned `seed.previewToken` with the chosen IDs: it binds this displayed set for 24 hours without granting subscription access. Refresh an expired preview before adoption.

## Rate limits and daily budget

Authenticated API and MCP calls share the plan holder’s daily allowance: Peek 30 or Panda 1,000 calls, reset at 00:00 UTC. The standard per-minute rate limit also applies; honor Retry-After and daily-call reset headers on 429 responses.