# Adopt a starter board

Track selected apps from a starter preview in a real board for the credential tenancy.

## 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: POST /v1/starter-boards/{nicheKey}/adopt

- Method: `POST`
- Path: `/v1/starter-boards/{nicheKey}/adopt`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `content:write`
- MCP tool: `adopt_starter_board`
- MCP action: `adopt`

## 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. |
| `selectedStoreIds` | body | string[] | yes | Distinct iOS App Store IDs from this preview: up to 12 for a curated niche, up to six for an app seed. Peek selects one; Panda may select the prepared set within its remaining allowance. |
| `previewToken` | body | string | no | Required for app-<numericStoreId>: copy seed.previewToken from the preview response. Expires after 24 hours; optional for curated niches. |

## 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.
- 409 conflict when the write would duplicate an exclusive row.

## Request

For a curated niche key, selected IDs must belong to that niche. For `app-<numericStoreId>`, send the preview token and select only IDs from that signed candidate set. Adoption keeps the apps shown in the preview without rerunning similarity. Board ownership, entitlement, tracking allowance and stored app validation remain canonical.

```
curl --request POST 'https://api.peekpanda.com/v1/starter-boards/calorie-tracking/adopt' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --header 'content-type: application/json' \
  --data '{"selectedStoreIds":["6480417616"]}'
```

## MCP request

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

```
{
  "name": "adopt_starter_board",
  "arguments": {
    "request": {
      "action": "adopt",
      "params": {
        "nicheKey": "<nicheKey>"
      }
    }
  }
}

```

## Response

The real board ID and the tracked App Store IDs. The caller must have an active PeekPanda entitlement, `content:write`, and room under the plan holder’s tracked-app allowance. 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.

```
{
  "boardId": "11111111-1111-4111-8111-111111111111",
  "trackedStoreIds": [
    "6480417616"
  ]
}

```

## 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.

## Errors and limits

400 `invalid_request` for malformed, duplicate or out-of-preview IDs, a missing/expired/invalid app preview token, or selecting multiple apps on Peek; 402 `subscription_required` without an active plan; 403 `authorization_required` without `content:write`; 404 `not_found` for an unknown niche or selected app missing from the stored catalogue; 409 `tracked_app_limit` when the plan allowance would be exceeded; and 429 for per-minute or daily call limits. On a daily cap, honor `Retry-After` and the daily reset headers.