Return metadata for the service API key used on this request.

• Works with any valid database-backed service API key, including api:*, planner:*, and the least-privilege studio:sync key.
• This endpoint introspects only the current bearer key and never returns the raw secret.
• Use expiresAt, expiresInSeconds, expiresInDays, and rotationRecommended to warn users before local apps lose API access.
• rotationRecommended becomes true during the final 14 days before expiration.
• Use a service API key created in workspace settings to retrieve expiration metadata.

Return the latest supported ShipyardKit SDK version.

• No workspace credential is required because the SDK release is global rather than tenant-specific.
• ShipyardKit 0.25.0 remains server-compatible without a contract-version request header.
• ShipyardKit 0.25.3 declares API contract version 1 so storage-provider changes remain behind the HTTP/JSON API.
• Responses may be cached for five minutes.
• Native tools should retain the last successful value and use their embedded SDK version as an offline fallback.

Return basic MCP endpoint metadata.

• Requires a database-backed service API key with a planner scope, such as planner:read, planner:write, planner:ai-status, planner:tasks, or planner:create.
• Generic api:read/api:write keys are not accepted for MCP. Legacy api:full is not user-creatable and never implies dedicated sensitive scopes.
• Admin-created service keys can be restricted to comma-separated product slugs.
• This is useful as a quick authenticated health check for MCP clients and setup scripts.
• The MCP endpoint is hosted on the same Worker as the app and resolves workspace context the same way the stable API does.

Call the hosted planner MCP server over JSON-RPC.

• Reads require planner:read or a planner mutation scope that implies read.
• create_planner_item requires planner:create or planner:write.
• set_ai_work_status and mark_testing_needed require planner:ai-status or planner:write.
• Planner task mutations require planner:tasks or planner:write.
• Supported MCP methods: initialize, ping, tools/list, tools/call, and notifications/initialized.
• MCP returns curated planner/product fields instead of raw admin database rows.
• MCP writes are recorded in the operator audit log with service key identity, target id, changed fields, IP, and user agent.
• MCP rejects obvious credentials in AI context, notes, summaries, and task titles; existing context is redacted on MCP reads when it matches common secret patterns.
• MCP enforces conservative AI status transitions. AI cannot move do_not_touch (shown as No AI Action in admin) directly to ready.
• AI work status is internal planner state and never changes public roadmap status by itself.
• AI work statuses: do_not_touch, clarification_needed, ready, in_progress, testing_needed, blocked.
• AI clarification requests are stored separately from human-authored aiWorkContext so AI questions do not overwrite instructions.
• do_not_touch is shown as No AI Action in admin and is the default so existing planner items are not AI-workable by accident.
• list_ai_work intentionally includes No AI Action/do_not_touch items so AI clients can show the full app planner while treating those items as non-selectable.
• Available tools: list_products, get_product_planner, list_ai_work, create_planner_item, update_planner_item, set_ai_work_status, request_clarification, mark_testing_needed, list_planner_tasks, create_planner_task, update_planner_task, delete_planner_task.

Mark selected AI work as testing needed after implementation.

• This is a tools/call request to /mcp, not a separate HTTP path.
• Requires planner:ai-status or planner:write.
• Updates aiWorkStatus to testing_needed and appends implementation/testing notes to aiWorkContext.
• Allowed only from AI workflow states that can transition to testing_needed, such as in_progress.
• Does not change request.status or product.workingVersionStatus.

Return the Apple Connect analytics dashboard payload used by the admin area.

• This route requires bearer auth for scripts and native clients. Admin sessions may also access it when signed in.
• The payload includes studio metadata, app filters, summary cards, trend data, top apps, recent breakdowns, and sync runs.

Recover the exact Planner create committed for a mutation ID.

• Used by native Planner clients to inspect an ambiguous create after a timeout, disconnect, or crash.
• The lookup is workspace-scoped, never returns the stored mutation key or digest, and returns 404 when no create committed.

Return Cloudflare edge analytics (visits, bandwidth, top paths) for the current workspace hostname.

• Web analytics must be configured for the workspace. Check configured and available in the response before displaying metrics.
• The workspace hostname list is derived server-side from the workspace slug + any active custom domain, including apex and www variants.
• If hostname is supplied, it must match one of the allowed hostnames for this workspace.
• Shared-host API clients should include ws=<workspaceSlug> so the request resolves the intended workspace.
• The payload includes configured, available, error, hostname, days, totals, trend, topPaths, allowedHostnames, selectedHostname, cached, refreshedAt, and expiresAt.
• totals.uniqueVisitors is a best-effort period unique-IP count; trend[].uniqueVisitors is daily bucket-level. Both may be null when Cloudflare does not expose the metric for the current token/schema.

Return current Asks and announcements for a mobile app.

• Requires a mobile feedback token from POST /v1/auth/mobile/public-session.
• Pass product=:slug.
• Returns the canonical asks and announcements collections.
• Add history=1 to include non-live engagement items.
• Records a Device Activity Event used by admin analytics.

Return mobile Asks only.

• Requires a mobile feedback token.

Return mobile announcements only.

• Requires a mobile feedback token.

Submit a mobile Ask response.

• Requires a mobile feedback token.
• Body shape depends on Ask type.

Record a mobile announcement event.

• Requires a mobile feedback token.

Return engagement totals for native/admin dashboards.

• Requires a service key with api:read.
• activeDevicesAllTime is the distinct non-simulator Device Activity installation count.
• deviceActivityEvents is the sum of stored Device Activity event counts.
• deviceActivityDays is the stored product/install/day row count.

List public products, or with auth include private ones.

• Public callers only receive products with visibility=public.
• Authenticated callers can also read private products and filter by visibility.
• Pagination defaults to 50 rows and caps at 100. Responses include total, hasMore, and nextOffset; continue until hasMore is false.
• Each product includes publicUrl for the live site path and supportUrl when the workspace Support page is enabled.
• Each product includes top-level planning fields plus a planning object with productNumber, workingVersion, workingVersionStatus, and workingVersionProgress.
• Each product includes latestUpdateAt and daysSinceLastUpdate from published non-FAQ product posts.
• List responses include updatePriority for app products that are live, in progress, coming soon, beta, or ideas. Live app maintenance uses stale published updates plus synced downloads; stalled working versions and ideas use product/planner activity age.
• updatePriorityNumber is the numeric queue rank to show in apps. It mirrors updatePriorityRank for older clients.
• Use includePriority=0, includeLatestUpdates=0, or includeSupport=0 for lightweight product lists. Priority and days-since-update sorts force the enrichment they need.
• Authenticated callers also receive an appStore sync summary with the synced live version kept separate from workingVersion.

Fetch one product by slug.

• Private products return 404 unless a bearer token is present.
• The response includes publicUrl for the live site path and supportUrl when the workspace Support page is enabled.
• The response includes the same product planning fields, planning object, and update-age fields as the list endpoint.
• updatePriorityNumber is the numeric queue rank to show in apps. It mirrors updatePriorityRank for older clients.
• Use includePriority=0, includeLatestUpdates=0, or includeSupport=0 to skip optional enrichment.
• Authenticated callers can pass includePlanner=1 to include private planner items grouped by working version, future versions, and unassigned backlog.

Create a product.

• Only one studio product is allowed.
• Slug is generated from name when omitted and must stay unique.
• If iconKey is provided without iconUrl, the API stores /assets/:iconKey.

List posts for one product.

• status defaults to published.
• Any non-published status requires a bearer token.
• Each returned post includes productSlug, productName, productUrl, and publicUrl.

Check whether promo-code claiming is enabled and whether inventory is available.

Claim one App Store promo code when the product allows it.

• Returns 400 when Turnstile verification fails or is missing.
• Returns 404 when promo claiming is disabled for the product.
• Returns 409 when no codes remain.
• Returns 429 during the cooldown window.

Patch product metadata.

List posts across the studio or for one product.

• status defaults to published.
• Non-published statuses require a bearer token.
• Each returned post includes productSlug, productName, productUrl, and publicUrl.

Get one post by the same slug shape used by the public site.

• Published posts are public.
• Draft posts are hidden from unauthenticated callers.
• The response includes both post.publicUrl and product.publicUrl.

Legacy id-based detail read kept for backward compatibility.

• Prefer /v1/posts/:productSlug/:postSlug for new clients.

Read just the metrics for one post.

• Draft post metrics require bearer auth.

Create a post.

• productSlug is the main field, and sourceSlug is accepted as an alias.

Patch a post.

Delete a post.

Replace every metric row for a post.

Replace every image attachment for a post.

List deleted requests that can be restored within 30 days.

• Requires api:read. Only deleted rows in the last 30 days are returned. Cache-Control: no-store.
• Returns requests, total, limit, offset, hasMore, and nextOffset. Default and maximum limit are 200; page until hasMore is false.

List public roadmap items or, with auth, private planner items too.

• Pagination defaults to 50 rows and caps at 100. Responses include total, requestsHasMore, deletedHasMore, hasMore, and nextOffset. On a delta read, page while hasMore is true, including when requests is empty; keep the first serverTime and advance the cursor only after both streams finish.
• Public reads only include visibility=public.
• Public reads hide waiting_review and archived by default.
• Authenticated reads can filter by visibility and origin.
• ShipyardKit Roadmap screens should render cachedItems() first, then call normal pullRoadmapDaily() and update visible groups only when fresh content is returned. Ordinary opens must not use force: true.

Create a public user request or, with auth, an internal planner item.

• Public callers create waiting_review user requests.
• Public request creation is intended for first-party browser flows and enforces same-origin checks.
• When Turnstile is configured, public callers must include a valid turnstileToken or cf-turnstile-response value.
• Anonymous mobile apps can submit by using a scoped bearer token from POST /v1/auth/mobile/public-session.
• Authenticated callers can create private/internal planner items directly.
• Authenticated native Planner clients should send the same 8-128 character mutation ID in the Idempotency-Key header and idempotencyKey body field; retries return the original row and conflicting reuse returns 409.
• Public callers must provide productSlug or sourceSlug so the request can resolve to a product.
• sourceSlug is accepted as an alias for productSlug.

Read one request or planner item.

• Private, waiting_review, and archived items are hidden from unauthenticated callers.

Bulk-create planner items.

• Accepts either titles as an array or lines as a newline-delimited string.

Bulk-update planner or request items by id.

Patch one request or planner item.

• Enum fields are validated against the same tables the admin planner form uses, never coerced: an unknown status is 400 invalid_status, item type 400 invalid_item_type, visibility 400 invalid_visibility, each with an allowed array.
• sortOrder must be a finite number (400 invalid_sort_order) and targetDate must be YYYY-MM-DD or null (400 invalid_target_date).
• linkedPostId must name a post in this workspace, else 404 post_not_found. null or "" unlinks it.
• productId, productName and productSlugHint move together. Linking a product clears the name snapshot and slug hint; productId null or "" unlinks and keeps the sent name, the existing name, or "Unlinked idea", recomputing the slug hint from it.

Move one planner item to another product and/or release and place it in that group.

• A group is the set of items sharing a product and a release version; items with neither group together.
• The destination group is renumbered 1..n in one batch, exactly as the admin board does, so a client can apply group.items and match the web byte for byte.
• Absent fields keep their current value. Errors: 404 not_found, 404 product_not_found, 400 invalid_position, 400 invalid_sort_order.

Write a whole planner group's order in one call.

• Every id must exist in the workspace and be in the named group, else 400 group_mismatch with an offendingIds array.
• Ids the group contains but orderedIds omits keep their relative order and are appended after the listed ones, so a client that reordered a filtered view cannot silently drop rows.
• 400 invalid_ordered_ids when the list is empty, over 200 entries, duplicated, or contains a blank id.

Text or a URL in, planner items out.

• One line becomes one item. "title -- description" splits on the first " -- ", using the same parser as /admin/planner/capture, and new items take the next sort order in the product group, so a capture from a phone lands where a capture from the web lands.
• dryRun returns the parsed titles without writing anything, so a client can show "this will make 4 items" before committing a paste.
• Errors: 400 nothing_to_capture, 400 capture_too_large over 100 lines, 400 product_not_found, plus the same invalid_status / invalid_item_type / invalid_visibility / invalid_target_date bodies as PATCH.

List checklist tasks for one planner item.

Create one checklist task.

Update one checklist task.

Delete one checklist task.

Vote or unvote on a public roadmap item.

• Web clients get a jw_vote cookie.
• Public browser callers must submit from the same origin and include a valid Turnstile token when Turnstile is configured.
• Anonymous mobile clients can use a scoped bearer token from POST /v1/auth/mobile/public-session.
• Native clients can pass voterToken.
• Send {"unvote": true} to remove an existing vote.

List asset records.

Upload an asset with multipart form data.

• productSlug is the preferred field, and sourceSlug is accepted as an alias.
• Either productSlug or sourceSlug is required.

Read one asset record.

List published articles, or with auth include unpublished ones.

• Public callers only receive published=true articles.
• Authenticated callers can filter by published=true or published=false.

Read one article by slug.

• Unpublished articles return 404 unless a bearer token is present.

List waitlist signups.

• Supports filtering by productSlug, productId, and status.
• Returns count for the current page and totalCount for the full matching result set.
• Each signup includes productSlug, productName, inviteTargetLabel, inviteDestinationUrl, and inviteUrl when present.

Create or refresh a product waitlist signup.

• Public browser submissions are intended for first-party flows and enforce same-origin checks.
• When Turnstile is configured, public submissions must include a valid turnstileToken or cf-turnstile-response value.
• Bearer-authenticated callers can create signups without same-origin or Turnstile requirements.
• Duplicate emails per product are upserted rather than inserted again.

Create or refresh an invite link for one signup.

• Returns 400 when the product does not yet have a public destination such as TestFlight, App Store, website, or public product page.

Update one waitlist signup status.

Delete one waitlist signup.

Cacheable reads carry a weak ETag; send it back as If-None-Match to get a bodyless 304.

• Cacheable reads send Cache-Control: private, no-cache and Vary: Authorization. The client may store the body but must revalidate before every reuse, and no shared cache may store it at all.
• Routes that must never live on a device keep Cache-Control: no-store and carry no ETag: /v1/auth/*, /v1/studio-remote/*, /v1/settings, /v1/billing, /v1/waitlist, /v1/export, every /v1/member/* write, every error response, and all of /admin and /operator. no-store forbids keeping the validator too, so those routes cannot be revalidated by design.
• The tag is weak: W/"<32 hex>", the first 128 bits of the body SHA-256. Comparison follows RFC 9110 s13.1.2, so W/"x" and "x" match, * matches anything, and a comma-separated list is accepted.
• A 304 repeats ETag, Cache-Control, Vary, the CORS headers and the security headers, and carries no body and no Content-Length.
• No validator is attached to a write, an error, an HTML or streaming body, an already-encoded body, or a body over 4 MB.

Delta reads: only the rows whose updatedAt is later than the cursor, plus tombstones.

• Supported on GET /v1/requests, /v1/posts, /v1/products, and /v1/reviews/:productId.
• Every one of them, plus the GET /v1/reviews rollup, returns serverTime. Use it as the next updatedAfter: it comes from the server clock, stepped back one second so a row committed during the read is not skipped. A row seen twice is free when the client merges by id.
• GET /v1/requests returns deleted[] tombstones for soft-deleted requests to privileged callers, in the same 30-day window as GET /v1/requests/trash. GET /v1/reviews/:productIdOrSlug returns removed[] for reviews Apple has withdrawn. For request cursors older than 30 days, perform a full refresh before resuming deltas. Preserve the first page serverTime until all pages finish.
• A delta read is ordered updatedAt ascending then id, so limit/offset page it; a full read keeps the route display order.
• Anything that is not a full ISO-8601 timestamp is a 400, never a silently empty list. Tenant scoping is identical on both paths.

Revenue, costs, profit, monthly buckets, month-end projection, and the expense list.

• Scope billing:read. Member tokens from the native sign-in flow and workspace-bound service API keys are both accepted; browser cookies are never consulted.
• The workspace comes from the request Host. A bearer bound to another workspace is rejected 403 workspace_mismatch.
• Responses carry Vary: Authorization. A successful GET carries Cache-Control: private, no-cache and an ETag so a native client can revalidate with If-None-Match; writes and error responses carry Cache-Control: no-store.
• Dates are anchored to the workspace timezone and held back until a successful Apple sales report covers the day.
• revenue.gross is always null: Apple sales reports stored by Shipyard carry developer proceeds only.
• comparison compares the current calendar month to date against the same number of days in the previous month.

Create a cost line.

• Scope billing:manage.
• The JSON body is validated by the same function as the admin financials form action.
• Any invalid field returns 400 invalid_expense.

Replace a cost line.

• Scope billing:manage.
• Full replacement: send the same complete body as the create call.
• 404 expense_not_found when the id is not in this workspace.

Delete a cost line permanently.

• Scope billing:manage.
• There is no expense trash.

Queue health, review-sync state, and the newest twelve service jobs.

• Scope api:read.
• Returns queue health, current background jobs, and review-sync status for this workspace.
• sync.state is error when any job is failed-but-retryable, else running, queued, or idle.

Re-queue failed service jobs so a phone that sees a failed sync can restart it.

• Scope api:write.
• Body is optional: jobId retries one job from the runtime-status jobs array; omitting it retries every retryable job, newest failure first, up to 25 per call.
• Retryable means exactly what counts.failedRetryable counts: status is failed and attempts < maxAttempts.
• Attempts are not reset, so a retry spends one of the remaining attempts and an exhausted job stays refused.
• An analytics.apple_sync_run job also has its Apple sync run failed days reset to queued first, before the job is retried.
• Retrying when nothing is retryable is a success with retried: 0, not an error.
• 404 not_found when the id is not in this workspace; 409 not_retryable, carrying the offending job, when it has exhausted its attempts or is not failed at all.

Portfolio and per-app rollups, Apple totals, and request/post counts in one call.

• Scope analytics:read.
• The window ends yesterday because Apple sales reports and device activity both land a day behind.
• apple is null when the workspace has no App Store Connect connection, rather than reporting zeros.
• An app carries null units and proceeds when no Apple row maps to it.
• momentum and portfolio.weekOverWeek are percent change in active devices between the last two complete weeks.
• Simulator traffic is excluded from every device count.

Publishing cadence buckets and trajectory from publication dates only.

• Scope api:read.
• No traffic or engagement data is involved.
• Buckets are dense: a month with no posts is present with zeros.
• trajectory ignores the in-progress month, so a partial month never reads as a slowdown.

The grouped planner board with each item’s checklist tasks.

• Scope api:read.
• Items are serialized exactly as the privileged GET /v1/requests read, minus the idempotency bookkeeping columns, plus product and tasks.
• At most 500 items are returned; counts.truncated says whether more exist.
• release view keeps empty groups so the board renders its columns; status view drops them.

Every sketch in the workspace, newest change first.

• Scope api:read.
• nodeCount and edgeCount are computed from the stored document, so a list can say "23 objects" without shipping every document.

Create an empty sketch at revision 1.

• Scope api:write.
• 400 invalid_name when the name is empty or over 120 characters.

Search the workspace for products and planner items a sketch can reference.

• Scope api:read.
• Entities are shaped exactly as the admin sketch editor's, so a node created on a phone and a node created on the web are the same node.

Create a private planner item from a sketch node and keep it linked.

• Scope api:write.
• The web returns only entity. This route also returns the full privileged planner row, so a client can drop the new item straight into its planner cache without a refetch.
• 400 invalid_title when the title is blank, 400 invalid_product when the product is not in this workspace.

One sketch with its document and every entity the document references.

• Scope api:read.
• The document is normalized on the way out, so a client never has to defend against a shape the web wrote before the validator existed.
• 404 map_not_found when the id is not in this workspace.

Save a sketch optimistically against the revision the client last read.

• Scope api:write.
• A 409 map_conflict carries the current revision and the current sketch INCLUDING its document. The admin web 409 does not: a browser can open a second tab to see what it lost to, a phone cannot, so the refusal has to contain the winning document for a "Keep mine / Take theirs" prompt.
• 400 invalid_name, 400 invalid_revision, 400 invalid_document (the message is the document validator's own reader-facing text, e.g. "Sketches support up to 400 objects.").
• 413 payload_too_large over 900 KB, 415 unsupported_media_type for a non-JSON content type, 404 map_not_found when the sketch does not exist.

Delete a sketch permanently.

• Scope api:write. There is no sketch trash.
• 404 map_not_found when the id is not in this workspace.

The 40 newest saved versions of a sketch, newest first.

• Scope api:read.

Restore an earlier version of a sketch; the current version stays in history.

• Scope api:write.
• The path is /restore, not the web's /history/restore: the member surface keeps one verb per path segment.
• 409 map_conflict uses the same envelope as PUT. 404 revision_not_found when that version does not exist.

Copy a sketch under "Copy of <name>".

• Scope api:write.
• Returns the new sketch rather than the web's redirect.

List the workspaces the signed-in Clerk user may open from a native app.

• Browser leg only: authenticated by the Clerk cookie session, restricted to same-origin requests, and never cached (Cache-Control: no-store, Vary: Cookie).
• No bearer token is accepted and none is returned. The endpoint mints nothing.
• Eligibility matches the sign-in callback: an active owner/admin membership on an active or trial workspace, matched by Clerk identity or an unclaimed email invitation.
• On a workspace host the tenant pins the answer to at most one entry; on the canonical app host every eligible membership is returned, bounded to 25.
• Returns 401 without a Clerk session, 403 cross-origin, 503 when mobile auth is unconfigured.

Rotate a live member token for a fresh 30-day token and revoke the presented one.

• Member bearer only, scope api:read. Rate limited to 30 attempts per 15 minutes, like /exchange.
• Call it on the workspace host returned as baseUrl: the workspace comes from the request Host, not from the token.
• No request body. The response is exactly the /exchange shape with a new token and expiry; scopes, role, and native client carry over.
• The presented token is revoked in the same conditional update that mints its successor, so exactly one concurrent refresh wins and the old token then fails ordinary authentication with a clean 401.
• There is no eligibility window; clients refresh on launch when the stored session is within seven days of expiry.
• Refusals are 401 with error token_expired, token_revoked, membership_inactive, or unauthorized. 429 rate_limited leaves the current token usable.
• Refresh uses the existing member bearer token and does not require a browser sign-in session.

Recovery inbox: list the notification intents this member's own Hosts have queued.

• Member bearer, scope api:read. Cache-Control: no-store, Vary: Authorization.
• Rows are joined through the Host, so an intent is visible only to the workspace and member that owns that Host.
• An unknown, foreign, or deleted hostId returns an empty list rather than 404: existence is never revealed.
• The projection is the same content-free allowlist as GET /status. No title, body, project, task, source, log, diff, endpoint, or credential exists in these rows.
• kind is one of hostOffline, captainNeedsAnswer, reviewReady, workBlocked, deploymentSucceeded, deploymentFailed, verificationWaiting. Intents are retained for seven days.
• A returned intent is not evidence that a push was delivered or viewed.

Current member/workspace ids and bounded Host lease summaries.

• Member bearer, scope api:read.
• Deliberately returns no workspace name, slug, billing, or account metadata, and no host endpoint, APNs token, or member email.
• Pairing assertions, host leases, notification registration, and inbox recovery use this same workspace origin and bearer authorization.

List the public roadmap feed or authenticated planner groups.

• Returns both roadmap and requests keys with the same rows.
• Only public items are returned by default.
• waiting_review and archived are hidden by default.
• Authenticated planning=1 returns private/internal planner fields and hides only archived items by default.
• grouped=1 returns a planner object grouped by current working version, future versions, and backlog.