Tool reference
Products, recommendations, saved references, feedback and product trends.
MCP gives an agent a named tool interface to Nabit's existing product services. The server applies OAuth identity, workspace roles, product access, Credits and rate limits. MCP is not a separate balance or an unrestricted public API.
The connected server's tool schemas are authoritative for parameter types and required fields. The following 31 tools describe the current interface. Use IDs returned by Nabit and let the host agent orchestrate the steps.
Connection and account
| Tool | Use and side effects |
|---|---|
get_connection_status | Check connectivity, workspace authorization, plan access and plugin updates. Does not return credentials or install updates. |
get_account_profile | Read the authenticated account's stable ID and profile. Does not accept an account selector. |
get_account_usage | Read Credits, current recommendation prices and optional history. Runs normal allowance reset / hold cleanup; does not buy Credits. History is limited to owners and admins. |
Products
| Tool | Use and side effects |
|---|---|
list_products | Find products by name or URL; optionally include archived products. |
get_product | Read product facts before matching or editing. |
preview_product | Read a public official product URL. Makes an external lookup; does not create a product. |
create_product | Save structured product facts. Does not request recommendations. |
update_product | Update supplied fields; omitted fields stay unchanged. |
archive_product | Archive a product, retaining its data. |
restore_product | Restore an archived product. |
Recommendation batches
| Tool | Use and side effects |
|---|---|
request_recommendations | Ensure the current batch exists for productId; can reserve Credits and queue matching. Reuses the current matching batch. |
get_recommendation_batch | Read the current batch or poll a snapshotId. Can settle existing holds and queue normal explanations. Does not ask for another batch. |
next_recommendation_batch | Request another batch with productId and the current snapshotId. Can reserve Credits; reuse the ID for a retry. |
get_video_recommendations | Read 1–5 items from the existing batch with exclusions, using the product ID as scopeId. Can settle held Credits. Does not create a batch or record returned history. |
get_video_details | Read a reference and existing analysis using snapshotId + hookId, or a legacy recommendationId. Returns authorized viewing links. |
request_video_analysis | Request or retry a Hook's match explanation with productId, snapshotId and hookId. Uses the existing analysis / charging behavior; does not produce a video. |
render_video_recommendations | Display completed recommendations in an MCP App or return viewing links. This renders reference cards, not a generated video. |
A read can settle an existing reservation
Recommendation reads are not a promise of zero billing side effects. The batch's delivered count determines settlement, even if your agent displays fewer rows. Re-reading a settled batch does not charge it again. See hold / commit / release.
Collections and feedback
| Tool | Use and side effects |
|---|---|
list_saved_videos | List the product's collection and its Nabit link. |
save_batch_video | Save a validated snapshotId + hookId after the user asks. |
save_video_recommendation | Save a current or legacy recommendationId; include snapshotId for an older matching result. |
remove_saved_video | Remove a saved reference when requested. |
record_video_feedback | Record an explicit open, watch, like, dismiss or not_interested action. Printing a link is not a watch. |
record_recommendation_decision | Record use, adapt or not_fit for a supported recommendation. |
mark_recommendations_returned | Record IDs selected for an agent response for future deduplication. Does not imply viewing. |
Preferences and schedules
| Tool | Use and side effects |
|---|---|
get_recommendation_profile | Read consented interests, language and timezone. |
update_recommendation_profile | Replace explicitly authorized topics and delivery preferences. Disabling interest consent clears saved topics. |
get_recommendation_settings | Read the product's research engine, update schedule and delivery preferences. |
update_recommendation_settings | Change schedules, engine or email delivery only as instructed. Uses normal budgets; a custom email can require verification. |
get_scheduled_video_digest | Read or reserve today's published digest and persist IDs for deduplication. Retries replay the same local-day digest. Does not start research or send external messages. |
Nabit schedules are separate from the host agent's scheduled tasks. Configure paid research and email delivery deliberately; a scheduled read does not authorize either.
Product trends
| Tool | Use and side effects |
|---|---|
get_trending_videos | Read existing tracking for one authorized productId. Does not start tracking. |
update_trending_tracking | Start or stop product tracking when requested, subject to existing service limits and budget. |
The demo heat board is not a public integration endpoint. Product trends are not a global heat-board feed.
Website and API availability
Image and video generation are available on the website, including Basic, subject to Credits and workspace spending permissions. They are not MCP tools or public /v1 operations. Internal website routes are not a public API contract.
For public /v1 access, use the recommendation-batch operations below. Legacy research operations are not part of this HTTP API.
Public /v1 API
The following HTTP routes reuse the existing capability and recommendation services. They require an existing OAuth Bearer access token with current workspace consent and scope nabit:recommendations. API-key authentication is deferred to milestone 4. MCP continues to use OAuth. This documents the implemented interface; local implementation does not imply a production deployment. The documentation-only preview does not mount authenticated API routes.
| Method and path | Parameters | Existing capability |
|---|---|---|
GET /v1/recommendations | Query: required productId; optional snapshotId, language | get_recommendation_batch; reads current batch when snapshotId is omitted |
POST /v1/recommendations | JSON: required productId; optional action (ensure by default or next), language, boolean retry; next requires the current snapshotId | request_recommendations or next_recommendation_batch |
GET /v1/trending | Query: required productId | get_trending_videos; reads existing product tracking |
Use product IDs returned by MCP list_products or your Nabit workspace. The API does not accept account/workspace selectors, upstream endpoints, arbitrary operations or extra parameters. Duplicate query parameters are rejected. IDs must be nonempty strings, other than *, up to 160 characters for productId and 64 for snapshotId. language accepts en (default) or zh-CN. POST accepts a JSON object up to the existing adapter's 16,000-character limit and no query parameters. snapshotId is accepted in POST only for next.
Example JSON for the POST request (send credentials only in the Authorization header):
{
"productId": "PRODUCT_ID_FROM_NABIT",
"action": "ensure",
"language": "en"
}Keep the returned snapshotId and poll GET /v1/recommendations?productId=PRODUCT_ID_FROM_NABIT&snapshotId=RETURNED_SNAPSHOT_ID. To advance, POST action: "next" with that source snapshotId. Retrying with the same source ID reuses the resulting batch instead of advancing twice. ensure reuses an existing current batch; retry: true allows retrying a failed current batch under the existing service rules. This is the existing snapshot replay behavior, not a new arbitrary idempotency-key contract.
Recommendation responses preserve the capability JSON: productId, snapshotId when present, status, items, billing and other existing batch metadata. HTTP 200 also covers queued, running, failed, missing, stale, empty, insufficient_profile and exhausted batch states; inspect status and keep the snapshot for polling. A missing current batch does not create one. Items include authorized viewing links and rights: "reference_only"; this is not an anonymous media-download API.
New batches share the website/MCP hold of up to 8 Credits and settle at 1 Credit per delivered Hook. GET reads can settle existing holds; repeated reads do not charge a settled delivery again. Website, MCP and /v1 share membership, roles, budgets, daily batch quotas and rate-limit buckets: 180 adapter requests per minute per workspace; recommendation ensure/next additionally share 30 requests per minute per workspace and product. API keys and per-key limits are not implemented here. See Plans & Credits.
Errors use the existing HTTP status and JSON fields error, code, and, when applicable, credits and rechargeUrl. This includes 400 invalid parameters, 401 missing/expired authorization, 402 insufficient Credits, 403 consent/plan/role/spending restrictions, 404 unavailable products or snapshots, 409 pending reconciliation, 413 oversized bodies, 429 rate limits and 503 unavailable services. All /v1 responses use Cache-Control: no-store. See Troubleshooting.
GET /v1/trending returns the existing product-trend service JSON, including its items when present. It never starts or stops tracking. There is no public heat-board, tracking-update, generic capability, research or generation route in /v1.