Browse documentation

🧭 Start Here

Blackcap Overview ✨ Blackcap Feature Catalog 🤖 AI Features 🧱 Technology, Administration, and Reliability Installation First Run

📘 User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

🛠️ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

🍽️ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation 🪄 Adapt Recipe and 🎲 Variations

📅 Plan Meals

Meal Planner

🛒 Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping 🔗 Chrome Extension Shop With

🧺 Manage Kitchen Inventory

🧺 Kitchen Inventory

🖥️ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

🧑‍🍳 Cook with Let’s Cook

🧑‍🍳 Let’s Cook 🧑‍🍳 Let’s Cook Controls and Timers

🤖 Use and Administer AI

🤖 AI in Blackcap 🤖 AI Providers and Connections 🤖 AI Seeds and Usage Support Chat

🔗 Use the Chrome Extension

🔗 Blackcap Chrome Extension 🔗 Chrome Extension Recipe Capture 🔗 Chrome Extension Shop With 🔗 Chrome Extension Release and Privacy

🎮 Play Games

Games and trivia Bramble Harvest — Player Guide Flavor Lab — Player Guide

🔌 Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

⚙️ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform — current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

⚠️ Troubleshoot Blackcap

⚠️ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting 🤖 AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

API Tester and Postman

Audience: System Admin, Org Admin, Data Admin, Developer, Support Related: Api · Database Administration · Regression Testing

API Tester exposes registered Blackcap endpoints with role-aware execution, sanitized examples, option resolution, authentication context, and Postman export. It covers API-token and session-authenticated endpoints, including feature-specific administrative surfaces.

The registry is the canonical API inventory. Documentation should describe endpoint purpose and safety boundaries without publishing live tokens, cookies, private organization identifiers, or credentials.

Durable Support Chat (registry 1.36). The Extension Support Chat message operation is asynchronous: it persists the user message, waiting assistant message, durable AI job, and provider-request snapshot before returning queued: true. Clients poll the existing session/history operation until the assistant message leaves waiting_for_ai. This makes the contract tolerant of normal Blackcap application restarts and avoids tying provider execution to the browser HTTP request.

API reconciliation, retired duplicates, and deprecated aliases

Registry specification version 1.36 retains the prior Mobile Recipe Photo/OCR, Multi API, Component Recipe, and package/update coverage while bringing the AI diagnostics contract up to date for Anthropic Claude, provider-owned correlation IDs, and Database Admin’s durable Create SQL Query workflow. The registry now exposes the Recipe Cart, Let’s Cook, and deliberate Recipe Sharing Component preview APIs, and the applicable recipe creation, Meal Planner, Shopping List, and Let’s Cook request schemas carry structured Component yield and component_choices. Mobile Add Recipe can attach real multipart recipe photos, and the staged review can be inspected, kept with built-in OCR, sent through the configured Recipe Photo AI profile, polled, and accepted without opening the Mobile UI. Blackcap now has one centralized lifecycle registry for both retired and still-deprecated compatibility URLs. Retired URLs are omitted from API Tester. The only retained compatibility routes are the two external OAuth callbacks, which are intentionally excluded from API Tester; all curated operations are canonical and non-deprecated. Blackcap-owned UI and regression callers use canonical routes.

Registry 1.36 retains the recent Kitchen Inventory and Let’s Cook administration coverage. The staged Product Photo and multi-item Kitchen Inventory Overview Photo upload routes are executable multipart API Tester operations, as is the shared Recipe-level Made It update used after Let’s Cook; each remains intentionally excluded from Multi API because file/multipart effects are outside the outer database transaction. Product/package mutations that are database-only—add Package, set remaining amount, and edit retained Product details—are explicitly Multi API eligible. The platform Ingredient Densities catalog now has JSON list/add/save APIs in addition to the Configuration UI; those operations are database-backed and Multi API eligible. Runout, overview-photo AI analyze/status/review, and the density-aware Inventory endpoints are all represented in the curated registry.

Registry 1.36 adds the physical Package freshness-date contract. The Package add, barcode acceptance, Product Photo Review, Put Away scan-acceptance, and AI review schemas expose the optional freshness fields, and the explicit Set Physical Package Freshness Date operation supports edit and clear without overloading unrelated Product metadata updates. The date mutation is database-only and eligible for Transactional Multi API; multipart Product/overview photo upload remains excluded for the existing file-effect reason.

Registry 1.36 also exposes FoodKeeper Shelf Life list/add/save plus the explicit USDA refresh operation. List/add/save are database-only; refresh is excluded from Transactional Multi API because it performs an external USDA fetch. Estimated Best By is intentionally absent from user-editable Package date enums because it is system-generated only. API Tester is an administration/debugging surface for the same catalog; matching precedence, storage-zone resolution, purchase-date fallback, no-estimate cases, and refresh/fallback lifecycle are documented in Kitchen Inventory and Platform Configuration.

Ingredient Catalog API Tester reconciliation. Five existing System Admin platform Ingredient Catalog routes are now explicitly registered: catalog search/paging (GET /api/platform/ingredients), ingredient save (POST /api/platform/ingredients/{ingredient_id}), TheMealDB sync start (POST /api/platform/ingredients/sync), sync status (GET /api/platform/ingredients/sync/{job_id}), and individual source-image refresh (POST /api/platform/ingredients/{ingredient_id}/refresh-image). The two persisted read operations are eligible for Multi API. Ingredient save, sync start, and image refresh are not Multi API eligible because visual/cache/audit effects, external provider calls, or downloaded files cannot be guaranteed to roll back with a containing transaction. All five remain permission-gated by system.configure; adding them to API Tester does not create new public application routes.

AI Usage provider filters explicitly offer openai, gemini, and anthropic. Quality Profile keys are treated as configured identifiers rather than assuming fixed names such as medium or high, so custom profiles such as claude-premier can be tested directly. AI failures expose a durable user-friendly failure_reason. For System Admins, a usage row's Provider ID prefers the provider HTTP request ID and falls back to a durable provider response/message ID when that is the only provider-owned correlation value retained. Quality Profile enable/disable/failure-streak management remains an administrative configuration workflow rather than a generic Multi API mutation.

Recipe Discovery/Plan Meals close-out (registry 1.36). The registry now describes the provider-neutral Recipe Discovery search contract, including recipe_type, total-pool limit, provider page_token, provider/request diagnostics, local Brave/Tavily paging, and the Agent Search best-effort result-image enrichment operation. Preview requests expose the real extraction hints (title_hint, description_hint, thumbnail_hint, and search_result) rather than the retired generic source selector. Search and image enrichment are intentionally excluded from Transactional Multi API because they perform external provider work. Plan Meals generation/status and the Meal Planner Recipe → Meal Item, Meal Item → Recipe Idea, and Recipe Idea → Meal Item conversion operations remain covered. Plan Meals quote/generate schemas also expose the optional 1,000-character planning_request; changing it changes the trusted quote fingerprint/approval context without changing the slot-based Seed price. They also expose use_recipe_preferences and minimize_recent_duplicates: taste preferences include compact Recipe Meal-Planner frequency, present Made It ratings, and high-level Meal Item/Recipe Idea summaries, while duplicate minimization adds one prior-30-day Meal Plan history block as soft variety guidance. When both are enabled, the history block is shared rather than duplicated. use_inventory remains availability-only for On Hand Only organizations; Full Inventory Tracking also contributes compact aggregate package quantity estimates. Plan Meals structured output is request-bounded to exactly the selected Meal Slot count and selected date/reference values to reduce provider omissions on large plans; local validation remains authoritative. Planning Request specializes matching selected dates/Meal Slots but never narrows the submitted selection; unmentioned selected Meal Slots are still planned normally. The trusted snapshot includes authoritative weekday/date mappings, and an otherwise-empty selected slot must receive a meaningful addition or provider validation fails. Endpoint notes make clear that models without grounded web search—including Claude and lower-capability OpenAI/Gemini profiles—can use the selected server-side Recipe Discovery provider (Agent Search, Brave, or Tavily). Find & Add changes Recipe source acquisition rather than Meal Item-versus-Recipe classification, and automatic source resolution is bounded to one Recipe candidate per Meal Slot.

The primary reconciled APIs remain canonical-only in API Tester:

  • Recipe Discovery: POST /recipes/discovery/preview; /preview-url is retired.
  • Recipe Share Links: POST /api/recipe-shares/link with recipe_ids, even for one recipe; the path-ID route is retired.
  • Recipe PDF email: POST /api/recipe-shares/email-pdfs; /share-recipe/{recipe_id} is retired.
  • Display content: POST /api/displays/assign-content; /api/displays/bulk-content is retired.
  • Display-scoped Let’s Cook: /api/kiosk/{display_id}/lets-cook/...; the nine /api/displays/{display_id}/lets-cook/... duplicates are retired.

Phase 2 additionally retires 21 internal Admin/action aliases after caller audits confirmed Blackcap no longer depends on them: six Background Operations job-action URLs, nine /admin/system/ai/... action/download URLs, two /admin/meal-planner/... API aliases, /back-to-menu, the Access Activity flag-update alias, the login-provider config-push alias, and the ingredients-only Database Admin cleanup alias. Phase 3 retires GET/POST /admin/shop-with-providers in favor of /admin/config/platform/shop-with-providers. Their canonical successors remain in API Tester where those operations are curated.

Only two compatibility method/path aliases remain callable: the Dropbox and Google OAuth callback aliases. They are external-provider compatibility endpoints and remain intentionally outside API Tester; all curated API Tester operations now use canonical, non-deprecated routes.

Calling any retired URL directly returns HTTP 410 Gone with X-Blackcap-Retired-Endpoint, X-Blackcap-Successor, and a successor Link; the old handler is not registered or executed.

Recipe creation, file formats, and Shopping List multiplier coverage

The curated Recipe creation schemas expose Cookbook Category assignments plus prep_minutes, cook_minutes, and stored total_minutes. When Total Time is absent, Blackcap can derive it once from the available timing fields and persist that value instead of recalculating it on every read.

Recipe file export/import testing covers Paprika, Schema.org Recipe JSON-LD (schema_org_jsonld), and Cooklang (cooklang). Export Recipes to File also accepts optional email_recipients, sender name, and message fields; supplying valid recipients emails the generated export instead of initiating a browser download. Multipart import accepts the matching Paprika, JSON/JSON-LD, Cooklang, and ZIP file extensions.

The Shopping Lists category includes Update Shopping List Recipe Multiplier for POST /shopping-list/{list_id}/recipe-multiplier. It exercises the same transactional rebuild used by the live Shopping List UI, including multiplier constraints and recipe-derived item regeneration. Completed Shopping Lists must be reopened before their recipe multipliers can be edited.

Component Recipe APIs

Component Recipes remain opportunistic: Blackcap does not persist a parent-to-Component relationship. The API Tester exposes the runtime planning boundaries used by the product:

  • POST /recipe-cart/component-preview previews direct Components for the current Recipe Cart.
  • POST /api/lets-cook/component-preview previews direct Components, required quantity, structured yield, recommended/selected multiplier, expected yield, warnings, and before/after placement before starting Let’s Cook.
  • POST /api/recipe-shares/component-preview returns optional direct Components for deliberate sharing together with their main-recipe context.

Recipe Cart and Meal Planner shopping-list requests and Let’s Cook session start requests accept component_choices. Recipe creation/capture schemas expose yield_quantity and yield_unit so Component Yield can be tested as first-class recipe data. These APIs do not create durable dependency links and do not infer Component semantics from ordinary third-party yield text.

Create Recipe and Combine Recipes (0.7.3-alpha)

The curated API Tester now includes Create Recipe options (GET /api/recipes/ai-original/options), start original generation (POST /api/recipes/ai-original/jobs), and idempotency-key lookup (GET /api/recipes/ai-original/jobs/lookup). It also includes Combine Recipes comparison (POST /api/recipes/{recipe_id}/adapt/compare), reviewed selection confirmation (POST /api/recipes/adapt/jobs/{job_id}/combine), and cancel/release (POST /api/recipes/adapt/jobs/{job_id}/comparison-cancel). The shared Adapt Recipe job-status, review/save and Bulk Adapt options/batch APIs remain the authoritative follow-up surfaces. Quality profiles and selected funding sources are supplied per operation; examples never assume access to credentials.

Transactional Multi API safety: Create Recipe options and submitted-job lookup are permitted read-only operations when the current session is authorized. Provider-generating Create/Compare/Combine requests are explicitly excluded: they reserve or settle AI Seeds and submit external provider work that cannot be rolled back by the database. Combine cancellation and Bulk Adapt review/save/finish are also excluded from unrelated Multi API batches because they finalize durable review state or affect recipe assets/Seed lifecycle. The UI exposes the specific reason for each exclusion. Use one API operation at a time for paid work, and recover ambiguous responses with the existing idempotency key and job status rather than submitting a fresh paid request.

The Plan Meals quote and generate contracts include create_original_recipes, create_recipe_profile_key, max_ai_recipes_per_slot (1–4, default 1), create_recipe_images, and create_image_profile_key. The quote returns minimum_seed_cost / planning_seed_cost and maximum_seed_cost / seed_cost, with separate create_recipe_estimate and create_image_estimate components. When original creation is enabled, the confirmed maximum is reserved once by the parent, then actual generation and image jobs receive transferred portions from that hold; the unused balance is released. The quote alone does not reserve anything, and child jobs do not reserve again against the account. Requote and reconfirm when the limit, options, dates, slots or selected profiles change. Poll GET /admin/meal-planner/plan-meals/jobs/{job_id} for saved original_recipes_created, original_recipes_failed, original_images_created and original_images_failed counts. Those counts represent actual outcomes, not the upper estimate. Provider interactions and child settlements retain separate AI Usage/job evidence; inspect them through AI Usage → What Happened rather than unfiltered job manifests.

Multi API audited sub-APIs and guided submission

API Tester 1.31 retains the audited Multi API eligibility in both directions and extends the audit to the recent whole-Meal/AI Meal Plan work. Transaction-safe operations are available as sub-requests, while endpoints with file/runtime/external/destructive effects or hidden writes are explicitly kept out even when they look read-only. The live endpoint details show Multi API eligible or the current exclusion reason.

The Transactional Multi API request builder is the preferred way to compose a request:

  1. Add an operation and select an API from the eligible endpoint list.
  2. Fill required path and query parameters; endpoint examples/defaults are prefilled when the registry provides them.
  3. Fill the schema-driven body fields. Required values are marked. Arrays and objects use JSON-aware editors and are no longer converted to strings.
  4. Review or edit Raw JSON body when needed. The tester parses it and validates object/array/scalar types, required properties, and enum values before adding the operation.
  5. Repeat for up to ten ordered operations, review the generated outer request, then execute with the normal mutating confirmation.

The server revalidates each endpoint ID and permission and runs every eligible operation inside one app-database transaction. A contained API failure rolls the transaction back. This includes Blackcap form endpoints that return a redirect after flashing an error or danger message; those redirects are no longer mistaken for successful sub-requests. Success/info flashes remain successful.

Configuration-backed Multi mutations refresh the effective runtime/config mirror only after the outer transaction commits. If a later operation fails, the database rolls back and the in-memory configuration is not left with an uncommitted value.

Examples of newly audited Multi operations include Cookbook Category create/update/assignment changes, Job Status review/ignore/mark-failed actions, AI Recipe Image accept/reject, Social Recipe Keep Current and Cancel, emoji aliases, and passive Display default/receiver/render/heartbeat configuration. The Kitchen Inventory audit additionally includes inventory_mobile_add_package, inventory_mobile_set_remaining, and inventory_update_product_details, while platform ingredient-density list/add/save operations are Multi-safe. Inventory/Made It image uploads stay API-Tester-executable but Multi-ineligible because they are multipart. Recipe/file saves, render/display-control actions, retries/job starts, backups, email, credential operations, external provider tests/searches, binary/file responses, and destructive actions remain excluded.

Recent Meal Planner coverage is assessed the same way. Rename Meal, Set Meal Slot People Served, and Bulk Set Meal Slot People Served are verified database-backed Multi API mutations; their Meal display refresh/audit work is deferred until the outer transaction commits, and people-served changes keep the normal AI Meal Plan invalidation-confirmation rules. Existing entry/whole-Meal moves remain Multi-capable, including the current behavior that can carry a still-valid saved AI Meal Plan when an intact Meal moves to the same Meal Slot on another date.

The newer AI endpoints deliberately split along transaction boundaries. AI Meal Image Options is now a true read and no longer creates a Meal identity row merely by opening the options dialog, so it remains eligible as a Multi API read. Plan Meal, Generate AI Meal Image, Meal image upload, and saved AI Meal Plan deletion remain single-operation APIs because they start provider/background work, upload files, spend AI Seeds, or deliberately remove durable product data. Meal Slot Summary and View Saved AI Meal Plan are also intentionally excluded from Multi API even though they are GETs: both refresh the saved plan's source fingerprint/staleness and may mark a plan stale as part of the read.

The Display API definitions were also reconciled with their production forms. Receiver Settings accepts refresh interval, status-bar default, fit/background mode, and kiosk idle return. Render Settings accepts timed Meal Planner and Let's Cook behavior fields. Display Advanced Settings is documented-only because its route consumes dynamic display_setting__... fields and there is not currently a stable curated display-scoped body contract.

Licensing status endpoint

The curated API Tester includes a Licensing → License Status entry for GET /api/license/status. It is a System Admin, read-only diagnostic surface. Its example intentionally uses a Trial so the registry documents the complete safe shape: effective state, online status, scope/term, License Number/Reference, License Period, signed issue/end/online-activation instants, Trial-expired/fallback-lock state, time remaining, entitlement revision/generation, masked/fingerprinted credential information, the safe nested entitlement, aggregate usage, and compliance. Perpetual responses omit or leave empty Trial-only values according to the live status payload.

The endpoint does not return the full License Key, encrypted credential, private signing material, host-local installation identity, or instance-reporting contact timestamps. License installation and replacement are intentionally excluded from API Tester and Postman export so credentials cannot accidentally enter request history, exported collections, regression artifacts, or generic API logs.

The existing System → Trigger Instance Report entry calls POST /api/system/instance-reporting/trigger. It is a confirmed System Admin diagnostic action, not a read-only status request: it accepts no caller-supplied instance identity/metadata, invokes the same registration/heartbeat reporting path used by Blackcap, and is intentionally excluded from Postman export. The authenticated License Details Refresh License Details button uses this reporting action and then reads /api/license/status to update the page without a full reload.

Blackcap package update operations

API Tester exposes these five System Admin entries only on package-managed Blackcap installations. They use the same update services and routes as Configuration → Platform → Updates and System → Blackcap Updates:

  • System → Blackcap Update Status — GET /admin/system/updates/status is read-only/passive. It returns Current, Previous, Version state, Approved target, allowed update actions, active Prepare/Apply progress, and the configured update policy. Its automatic_check.mode is heartbeat when Automatic check is enabled and manual when Manual only is selected. Reading status does not contact the Microwave Pie software delivery and instance management service and does not count as activity for the inactive-login timeout.
  • System → Check for Latest Blackcap Update — POST /admin/system/updates/check forces the same latest-version/candidate lookup as the System-page button. It remains available in either policy mode, refreshes persisted candidate/check state, and returns the normalized live status. It does not Prepare, Apply, restart, or restore Blackcap. Because it writes update-check state and audit metadata, API Tester treats it as a confirmed mutating action even though it does not modify customer data.
  • System → Save Blackcap Update Policy — POST /admin/config/platform/updates/save updates the package-scoped Manual only / Automatic check policy, the dependent auto-apply-on-restart option, the service-start success-notification window, and the Update History display count. API Tester requires mutating confirmation. Saving the policy does not itself check, download, prepare, apply, or restart Blackcap.
  • System → Blackcap Update History — GET /admin/system/updates/history returns the configured number of recent entries from the bounded host-persistent update history (10 by default, up to the 100-entry host retention ceiling), including versions, method, result, phase, and fallback details. Reading history does not contact the management service.
  • System → Blackcap Updater Preflight — GET /admin/system/updates/preflight reports whether the independent package updater is ready for activation. It does not check for an update or change the host.

When Automatic check is enabled, every accepted normal application heartbeat returns the Microwave Pie management service's current normalized update decision and Blackcap consumes it immediately. With Manual only, Blackcap ignores heartbeat update candidates and discovery occurs only through the explicit Check for Updates action. There is no independent time-based candidate suppression or second automatic candidate request after an accepted automatic-check heartbeat.

All five update entries are browser-session/System-Admin/package-install operations and are intentionally excluded from Postman export. Source/unmanaged installations do not list or serve them. They never expose package download credentials, License Keys, signing private keys, arbitrary filesystem commands, or arbitrary package URLs. API Tester deliberately does not provide a “run startup auto-update now” operation; automatic activation is tied to a genuine Blackcap service start and the saved policy.

API Tester details

Blackcap includes a standalone, logged-in API explorer/tester at:

/api-tester

This is intentionally not an Admin UI page and is not mounted below /admin. It has its own blueprint, templates, static assets, layout shell, endpoint registry, and guarded execution service.

Why Blackcap-native instead of Swagger UI?

The first implementation uses a Blackcap-native tester instead of bundling Swagger UI.

Reasons:

  • Blackcap self-hosted Raspberry Pi installs should not depend on external CDNs at runtime.
  • The tester needs mixed authentication behavior: normal logged-in browser session for web endpoints and manually pasted API tokens for Chrome Extension endpoints.
  • The endpoint list should be curated, not discovered automatically from every Flask route.
  • Sensitive values need Blackcap-specific masking rules.
  • The UI can stay lightweight and quick on a Pi.

The registry is still OpenAPI-style and exposed as JSON through /api-tester/spec, so a Swagger UI wrapper could be added later if it becomes useful.

Access Control

The tester requires a normal logged-in Blackcap browser session.

Routes:

  • GET /api-tester
  • GET /api-tester/context
  • POST /api-tester/context/switch
  • GET /api-tester/spec
  • GET /api-tester/options/<source>
  • GET /api-tester/postman-collection
  • GET /api-tester/postman-environment
  • POST /api-tester/postman-token
  • POST /api-tester/execute

Access is controlled by the permission:

api_tester.view

Mutating tester execution additionally requires:

api_tester.execute_mutating

The role mapping grants both permissions to System Admin, Org Admin, and Data Admin. Operator and Contributor roles do not receive API Tester access. The Admin sidebar shows 🧑‍💻 API Tester as the final item in the Tools group only when api_tester.view is available; the link opens the standalone tester in a new browser tab for the current Blackcap instance.

System Admins can switch the API Tester organization context to any non-deleted organization. Users with access to multiple organizations can switch among their own active memberships. The switcher uses Blackcap's existing session organization context, then reloads the curated spec so visible endpoints and permissions match the selected context.

The API Tester does not replace existing route permissions. The execution service validates the curated registry first, then executes the existing Flask route so the normal route/service permissions, organization scoping, CSRF behavior, API token checks, and endpoint-specific validation remain authoritative.

Authentication Models

Session-authenticated endpoints

Session endpoints run with the current logged-in browser session. They use the current organization context and include the CSRF token for state-changing requests.

Examples:

  • recipe search/list
  • recipe details
  • display assignment options
  • display state
  • job status rows
  • live performance resource snapshot

API-token endpoints

Token endpoints behave like the Chrome Extension. The user manually pastes a Blackcap API token into the tester UI.

Rules:

  • The token is not persisted server-side.
  • The token is not inserted into curl examples.
  • The token is not included in audit metadata.
  • The token is masked in the browser input unless the user explicitly shows it.
  • The browser input is intentionally marked to discourage password-manager autofill, and the masked token control is a text input with CSS masking rather than a normal password field.
  • The token can optionally be remembered in browser sessionStorage for the current browser session only. It is cleared by the Clear button, by disabling the checkbox, or when the browser session ends.
  • If the Blackcap Chrome Extension content script is installed for the current Blackcap host, the tester can ask the extension for the active token. This is a browser-side handoff only; Blackcap does not retrieve or expose stored token plaintext from server-side token records.
  • The API token organization determines scope for token-scoped endpoints.
  • Invalid, revoked, inactive-user, or disabled-organization token behavior remains controlled by the existing authentication/security services.

Examples:

  • /api/recipes/ping
  • /api/recipes/defaults
  • /api/extension/context
  • /api/recipes/add
  • /api/extension/recipes/capture
  • /api/extension/household-list/browser-bridge/context

Copyable cURL and authentication help

Each API Tester endpoint displays a cURL card built from the current request-builder values. The command uses the browser-visible Blackcap origin, includes the endpoint path/query/body/file arguments, and includes the authentication header shape appropriate for that endpoint. Copy cURL copies the complete command to the clipboard.

The adjacent Authentication Help action explains how the selected endpoint authenticates:

  • ordinary session endpoints use Authorization: Bearer <API_TESTER_BEARER_TOKEN> when called from a terminal; the popup can issue and copy the same signed 8-hour user/organization-scoped bearer token used by Postman;
  • API-token endpoints use Authorization: Bearer <API_TOKEN>;
  • paired Remote Display Client endpoints use Authorization: Bearer <REMOTE_DISPLAY_CLIENT_TOKEN>;
  • the Remote Display Client pairing endpoint uses its short-lived pairing_token in the request body and no Bearer token;
  • tokenized share endpoints explain the required share/public token in the path or query rather than inventing a session header.

Generated/copyable cURL never inserts a live API token, temporary bearer token, display-client token, pairing token, share token, password, API key, License Key, or similar secret. Token-like path/query/body values are replaced with named placeholders. If a body cannot be safely parsed, the reusable cURL shows <REQUEST_BODY> rather than copying opaque input. The API Tester request itself still uses the credentials deliberately supplied in the request builder; only the reusable cURL example is sanitized.

System Admins can run Consent Management Integration Status from the System category. The read-only endpoint is GET /api/system/consent-integration/status and is intentionally API-Tester-only rather than exported to Postman. It reuses the installation's existing registered-instance identity server-side, so the tester never asks for or displays the heartbeat token.

The diagnostic checks both network boundaries without a recipient address:

  • authenticated access to the Microwave Pie management service at tracking.microwavepie.com for the non-mutating Consent Management status contract; and
  • public HTTPS/TLS/routing access to consent.microwavepie.com/consent/health.

The response contains only sanitized hosts, paths, HTTP status, latency, advertised capabilities, and contract errors. It does not return installation secrets, recipient addresses, preference values, or Consent tokens and it does not change state.

Endpoint Registry

The curated endpoint registry lives in:

inky_admin/services/api_tester_registry_service.py

Each endpoint definition includes:

  • category
  • display name
  • HTTP method
  • path
  • description
  • authentication mode
  • required permission
  • organization scope behavior
  • path parameters
  • query parameters
  • request body schema/example
  • example response
  • success/error status codes
  • read-only vs mutating
  • notes and safety flags

Do not auto-expose every Flask route. Add endpoints to the registry only when they are useful, safe, and documented.

Multipart and file attachments

API Tester 1.17 renders file inputs separately from the structured metadata body whenever a curated endpoint schema declares a top-level field with format: binary or an array of binary items. The UI shows the selected file names, browser-reported MIME types, per-file sizes, and total size. Binary arrays support multiple files and preserve the same form key for every attachment; Social Recipe AI therefore sends repeated frames fields exactly as the production endpoint expects.

Files exist only in the outer API Tester HTTP request and the in-process target request. API Tester does not copy them into a persistent tester folder, session storage, audit metadata, curl examples, or browser storage. The target Blackcap endpoint remains authoritative for its own upload-size, MIME, permission, organization, retention, and processing rules. The API Tester request envelope is bounded just above the largest currently executable media endpoint so metadata and multipart boundaries do not accidentally lower the target route's 52 MB ceiling.

Current multipart operations include:

  • Mobile Add Recipe Submit — accepts one or more photos when add_method=capture, stages built-in OCR, and returns a capture-review id without saving a recipe yet.
  • Preview Recipe Import File — accepts one or more supported recipe export files and remains read-only.
  • Import Recipe File — accepts the same files plus selected recipe metadata and requires normal mutating-call confirmation.
  • Upload Social Recipe AI Evidence — requires the bounded video and can include repeated sampled frames, thumbnail, description, written evidence, duration, and capture metadata. Creating the AI job before this upload may reserve AI Seeds; successful media upload can start provider processing, so use a disposable/test organization when exercising the complete sequence.
  • Inventory Barcode Frame Decode — accepts a transient camera frame for barcode decoding. The raw frame is request-temporary and is not retained.
  • Temporary Product Photo — stages one product/package image for the single-item Product Photo review workflow.
  • Kitchen Inventory Overview Photo — stages an Inventory-level image that can contain multiple ingredients for the separate multi-item review workflow.
  • Made It update — accepts rating, notes, cleanup feedback, and an optional Recipe-level Made It photo. The update edits the shared Recipe record rather than creating per-user or per-session feedback.

The structured Copy Input diagnostic includes attachment field/name/size/MIME metadata but never file bytes. Curl examples show -F file placeholders/selected filenames rather than embedding content.

Recipe Photo/OCR workflow and manual/OCR duplicate identity

API Tester 1.19 introduced the same staged Recipe Photo workflow used by Mobile Add Recipe; it remains available in 1.31:

  1. Mobile Add Recipe Submit (POST /mobile/add-recipe) now uses executable multipart input. Set add_method=capture and attach one or more photos files. The response returns a capture_id and an awaiting_review state; no recipe is saved yet.
  2. Recipe Photo Review State loads the built-in OCR candidate and available AI/funding choices.
  3. Keep Built-in OCR Recipe Photo Result saves the deterministic candidate, or Start AI Recipe Photo Review starts the paid AI review after confirm=true.
  4. Get AI Recipe Photo Job polls the asynchronous result.
  5. Accept AI Recipe Photo Result saves the AI-reviewed candidate.

The manual and Recipe Photo finalization paths share a conservative duplicate check that is intentionally not used for URL, social, Recipe Discovery, or share imports. The identity excludes recipe title and recipe ID. Blackcap normalizes the first-source ingredient and instruction text, sorts ingredients because ingredient order is not identity-bearing, normalizes common unit/fraction/punctuation forms, then computes the versioned SHA-256 content fingerprint (manual-ocr-content-v1). Exact fingerprint matches update the existing recipe. Fuzzy OCR tolerance is allowed only for sufficiently descriptive recipes and requires very high ingredient/instruction similarity, comparable token counts, and identical normalized numeric/fraction tokens so a real quantity/time/temperature change is not silently merged.

There is no stored recipe fingerprint column. The fingerprint is computed when needed from recipe_edit_content.original_ingredients_text and recipe_edit_content.original_instructions_text, falling back to the effective content for older records that do not yet have original values. Once established, those original fields remain the identity basis through later edits, unit conversion, AI review, or a new matching photo. The Manual Recipe Add API response exposes updated_existing_recipe and a duplicate_match object when a match occurs; duplicate_match.fingerprint is diagnostic output, not persisted database state.

Because Recipe Photo AI can spend AI Seeds and sends uploaded images to the configured provider, exercise that branch in a disposable/regression/diagnostic organization unless the action is intentional.

Postman Collection Export

The API Tester can download a curated Postman collection through:

GET /api-tester/postman-collection

The route requires the same logged-in api_tester.view permission as the rest of the tester, but the downloaded collection does not contain any live secrets. It uses collection variables such as base_url, blackcap_api_token, blackcap_postman_token, client_token, pairing_token, recipe_share_public_id, and recipe_share_token.

The Postman collection is generated from the same curated registry and now follows an include safe runnable endpoints by default rule instead of maintaining a second category allowlist. This keeps ordinary additions such as Cookbook Categories, Voice Assistant diagnostics, License Status, Multi API, Recipe Quick View, and other safe session APIs aligned automatically with API Tester. API-token, remote-client, tokenized share, and safe session-authenticated endpoints can all export with the appropriate variable-based authentication. Endpoints opt out explicitly with postman_export=False when Postman is not a reasonable surface. Documented-only or unsafe/destructive operations, user/org lifecycle management, Database Admin, Data Purge, auth challenge flows, OAuth callbacks, webhooks, binary-only viewers, and normal page-shell routes remain excluded.

API route coverage review

The Postman/API Tester inventory is checked against the Flask Blueprint route source so new canonical /api/... endpoints are not silently missed. Compatibility aliases can be explicitly allowlisted when a canonical route is already represented. The current allowlist covers the /api/displays/... aliases for Kiosk Let’s Cook actions because the equivalent /api/kiosk/... paths are the canonical API Tester/Postman entries.

The current review includes AI Recipe Image generation/review, browser-session Social Recipe Imports, Recipe multiplier options, Cookbook Category hierarchy/assignment operations, missing Kiosk and Let’s Cook presentation actions, and Shop With skip/clear-skips operations. The generated candidate-image binary endpoint is registered for documentation/coverage but is intentionally excluded from API Tester execution and Postman because the current tester response viewer is text/JSON oriented.

The API Tester sidebar includes a Postman button that opens a dedicated setup dialog. The dialog contains the Postman collection download button, the environment download button, and a helper to copy blackcap_postman_token. The token helper calls POST /api-tester/postman-token, requires the same logged-in API Tester permission and a valid CSRF token, returns a signed 8-hour bearer token scoped to the current user and organization context, and never logs the raw token. Treat the copied token like a password until it expires.

The generator lives in:

inky_admin/services/api_tester_postman_service.py

When adding a new endpoint, the Postman generator now assumes a safe runnable API Tester endpoint is useful unless the endpoint definition explicitly sets postman_export=False or falls into an intentionally excluded administration/browser-only class. API-token endpoints, tokenized public/client endpoints, practical session-authenticated actions, and safe multipart uploads therefore stay aligned automatically; binary request schema fields export as Postman file form-data rows and binary arrays note that the same key should be repeated for additional files. Destructive lifecycle/admin/database operations should remain documented-only or explicitly opted out.

Display render settings and timed Meal Planner behavior

The Display Administration category includes Update Display Render Settings for POST /admin/displays/{display_id}/render-settings. This is a form-backed Admin route, so API Tester sends the structured body as form fields. In addition to width, height, and orientation, the endpoint now documents the timed Meal Planner fields:

{
  "timed_meal_plan_behavior": "recipe",
  "restore_default_after_slot": true,
  "auto_show_lead_minutes": 0,
  "auto_show_behavior": "first_recipe",
  "voice_lets_cook_display_mode": "full_recipe",
  "show_setup_step_in_full_lets_cook": false
}

Use timed_meal_plan_behavior=recipe for passive timed recipe display. Use timed_meal_plan_behavior=lets_cook for any display type. Kiosk displays and touch-enabled hosted web receivers show the interactive Let’s Cook UI, while local e-ink, non-touch hosted receivers, mock displays, and remote clients render the display-only Let’s Cook preview. voice_lets_cook_display_mode controls whether the display render surface uses full-recipe, voice-only current-step, or all-session current-step Let’s Cook. show_setup_step_in_full_lets_cook controls only whether full-recipe Let’s Cook includes generated Setup/Step 0. Database Admin exposes these raw displays fields for troubleshooting.

Organization cooking preferences

The Organization Management category documents both current-org and System Admin organization update routes. Their request body schemas now include the cooking-preference fields that appear near Preferred Recipe Units on the Organization page:

{
  "recipe_preferred_units": "as_written",
  "show_full_recipe_review_before_current_step_present": "1",
  "show_full_recipe_review_before_current_step": true
}

show_full_recipe_review_before_current_step is org-scoped, defaults to true, and affects current-step Let’s Cook render surfaces. It is not a display setting and does not change saved recipes.

Shopping List checked-state endpoint

The Organization Management category includes current-org and by-id profile update endpoints with preferred_time_format (12h / 24h) in the generated form schema. The Create Organization endpoint uses the same System Admin form field names as the UI: preferred_time_zone, preferred_time_format, preferred_locale, admin_email, admin_display_name, and invite_message.

Meal Planner slot create/update endpoints expose start_time and end_time as native time controls. The request value is canonical HH:mm; the visible picker UI can follow the tester PC/browser clock preference, matching the production Meal Planner setting page.

The Shopping Lists category includes Update Checked Shopping Items for POST /shopping-list/{list_id}/toggle. This entry documents both the legacy single-item shape and the rapid Shop a List multi-item shape. Use the updates array when testing rapid checkoffs so the server receives the shopper's desired final state for each row. Prefer item_id in each update because display indexes can change after checked items are sorted. section/index remain a legacy fallback.

A useful API Tester check is to create a manual list, add several rows, then send a compact payload like:

{
  "compact": true,
  "updates": [
    {"section": "unparsed_or_unquantified", "index": 0, "item_id": "sli_example_1", "checked": true},
    {"section": "unparsed_or_unquantified", "index": 1, "item_id": "sli_example_2", "checked": true},
    {"section": "unparsed_or_unquantified", "index": 2, "item_id": "sli_example_3", "checked": true}
  ]
}

The response should include verified: true, updated_count, updated_ref_count, and current counts when the request targets a single list. If verified is missing or false, treat that as a regression because the UI relies on this endpoint to avoid rapid-checkoff state loss.

Extension Support Chat workflow

The Chrome Extension category exposes the complete documentation-grounded Support Chat sequence using the same API-token user and organization ownership rules as the Extension itself:

GET  /api/extension/support/chat/status
POST /api/extension/support/chat/session
POST /api/extension/support/chat/message
GET  /api/extension/support/chat/session/{session_id}
POST /api/extension/support/chat/session/{session_id}/resolution
POST /api/extension/support/chat/session/{session_id}/email
POST /api/extension/support/chat/session/{session_id}/escalation
POST /api/extension/support/request

Use status → session → message for normal conversation testing. Use resolution when the answer solved the issue, email for a retained terminal transcript, or escalation → support request for the reviewed human-support path. The surface_key choices are generated from the same authoritative Extension surface registry used by the server rather than maintained as a separate API Tester enum.

Support Chat ownership is (organization_id, user_id), resolved from the API token. It is not IP- or browser-scoped. A token cannot read another user's conversation or a conversation from another organization. The API Tester must not expose cookies, page DOM, provider tokens, internal support context, or other unsafe Extension state.

Social Recipe Extension Workflow

The Chrome Extension category now documents the complete deterministic-first social recipe workflow:

  • preview captured evidence without persistence
  • submit/poll an organization-scoped social import
  • run AI preflight only after deterministic extraction
  • inspect anonymous exact-post reusable conversions
  • load AI profile/cost options
  • create and poll a social AI job
  • review/import partial or complete candidates
  • cancel an active review
  • inspect the bounded multipart media contract

Use social_recipe_imports and social_recipe_ai_jobs option sources for import/job ID fields. The Social Recipe AI media endpoint is executable in API Tester 1.17: choose the required video, optionally attach repeated frames plus thumbnail/description/written-evidence files, and provide the normal metadata form fields. The preceding AI job-creation call can reserve AI Seeds and successful media upload starts provider processing, so use a test organization and normal mutation confirmation. The preview examples keep provider content IDs as strings; this is essential for 19-digit TikTok IDs, which exceed JavaScript's safe integer range. Pinterest examples include pinterest_current_pin_matched so stale single-page navigation data can be rejected explicitly.

The API Tester remains a diagnostic surface, not a replacement for the extension's browser capture. It cannot reproduce DOM isolation, active-player geometry, or thumbnail pixels, but it can verify server identity enforcement, deterministic completeness decisions, persisted import state, AI review state, and safe failure diagnostics.

Execution Flow

The API Tester uses:

POST /api-tester/execute

Execution flow:

  1. Confirm the user has api_tester.view.
  2. Look up the endpoint in the curated registry.
  3. Confirm the endpoint is visible to the current user role/permissions.
  4. For mutating calls, require api_tester.execute_mutating and explicit checkbox confirmation.
  5. Build the target path from declared path/query parameters only.
  6. Parse and validate the structured metadata body; for multipart endpoints, validate only file fields declared format: binary in the curated schema and attach the browser-selected request-temporary files.
  7. Add either session authentication/CSRF headers or an API token authorization header.
  8. Execute the existing Flask route in-process, preserving repeated multipart fields such as Social Recipe frames.
  9. Sanitize response headers/body before returning them to the tester UI.
  10. Audit the tester execution without storing secrets or uploaded file bytes.

The execution service lives in:

inky_admin/services/api_tester_execution_service.py

Response and header secret masking lives in:

inky_admin/services/api_response_sanitizer_service.py

Initial Endpoint Coverage

Current curated categories include:

  • API Tester
  • Current User
  • Status / Runtime
  • Recipes
  • Recipe Discovery
  • Displays
  • Emoji
  • Meal Planner
  • Shopping Lists
  • Jobs
  • Performance
  • Let’s Cook
  • Backups
  • Chrome Extension
  • Kiosk Display

The second pass added more typed path/query inputs, including select lists, booleans, numbers, dates, URLs, and request-schema display where a JSON body is expected.

The third pass separated examples/placeholders from actual defaults. Regular path/query inputs now start blank, while context-derived fields such as org_id use the selected API Tester organization context. When multiple organizations are available, organization fields use a browser typeahead/datalist containing the allowed organization IDs. This avoids fake defaults like org_... while still making valid context IDs easy to use.

The third pass added response-body search. The fourth pass made that search toolbar always visible whenever the response card is visible. Clicking inside the response area and pressing Ctrl+F/Cmd+F now focuses the in-response search box instead of showing the browser-level page search. Use Enter/Shift+Enter or the arrow buttons to move between matches.

Current curated coverage now also includes Recipe Sharing status/summary endpoints, Support Request status, Emoji cache status/rebuild, additional Meal Planner actions, and additional Chrome Extension Shop With review endpoints.

The fifth pass adds a documented API Tester options endpoint, more kiosk display endpoints, additional Let’s Cook control/timer endpoints, context-aware kiosk display typeahead values, Shop With provider/store-mode option sources, safer token session storage, and an optional Chrome Extension token handoff.

The sixth pass expands curated coverage again, including more Recipe Discovery, Meal Planner slot/move/settings, Recipe Sharing, Shopping List item/cart, Emoji registry, backup-provider test, and Noun Project test endpoints. Endpoint category groups in the sidebar are now collapsible and start expanded by default, so larger groups such as Backups and Chrome Extension stay easier to navigate as the registry grows.

The seventh pass fixes the public spec description builder and keeps endpoint descriptions focused on what each endpoint is for. Authentication requirements are shown in their own metadata area, so descriptions should explain the use case, workflow, or troubleshooting value instead of repeating the auth model.

The eighth pass fills in the remaining known /api and /kiosk Flask routes from the static route inventory. New coverage includes more Recipe Sharing lifecycle/import/export endpoints, scheduled display-assignment cancellation, the kiosk page route, and Remote Display Client pair/state/heartbeat/preview routes. Curated multipart upload routes can now be executable when their request schema declares binary fields; binary response/download routes remain Documented only until the response viewer has a safe binary-download execution flow.

Remote Display Client coverage now documents the full lifecycle:

Generate pairing code → Pair → Read state → Download preview
→ Heartbeat with physical-panel acknowledgement → Unlink

Deployed clients authenticate to state, preview, heartbeat, and unlink with Authorization: Bearer <client token>. The client_token query field remains only as an API Tester convenience. Heartbeat examples include the last physically displayed preview, physical update time, successful poll time, Waveshare panel type, grayscale mode, and four gray levels. The binary preview route remains Documented only.

The attached-local display Link/Relink and Unlink Admin routes are also documented but not executable from the tester. They change encrypted live client state and should be used through Display Details, where atomic relinking and waiting/error states are handled safely.

The ninth pass improves discoverability for the existing add-recipe API at /api/recipes/add. It is listed as Add Recipe API under Chrome Extension because it uses the same API-token flow as the extension, and endpoint search now matches individual words instead of requiring the whole typed phrase to appear contiguously.

The tenth pass adds the Recipe Library's session-authenticated add flows that do not live under /api: /add-recipe, /manual-recipe, and /select-recipe. It also documents the editable-content prepare/save routes and shows the archive route as Documented only because archiving is destructive and should stay behind stronger safeguards before tester execution is enabled. These routes remain separate from the Chrome Extension add-recipe API; no route cleanup or aliasing is required just to make them available in the tester.

The eleventh pass adds explicit request encoding metadata and broader coverage for older session routes outside /api. Endpoints can now declare request_encoding as json, form, multipart, query, or none; the execution service sends form-backed routes as form data while keeping the tester body editor as a structured JSON object of fields. New coverage includes legacy display actions, Job Status actions, Shopping List UI actions, Mobile UI actions, Kitchen Inventory mobile/admin flows, and a broader Settings category for scoped configuration, GeoIP/flag utilities, Noun Project rules, auth provider settings, organization login providers, MFA policy, and related configuration helpers.

The twelfth pass improves navigation for the much larger registry. Endpoint groups are now sorted alphabetically, endpoints inside each group are sorted alphabetically by display name, and group headers stick to the top of the sidebar while scrolling until the next group takes over. This pass also rounds out the remaining useful non-page action routes from the static route inventory, including Display Administration, Connections, Organization Management, User Management, Data Purge, Database Admin, additional Meal Planner routes, shopping department actions, and legacy compatibility routes. The curated registry now accounts for the remaining non-page action routes that are useful to document or test; login/auth challenge flows, OAuth callbacks, webhooks, public share callbacks, static/media routes, and normal HTML page shells remain intentionally excluded.

The thirteenth pass adds Postman collection export for externally useful API surfaces. The fourteenth pass expands that export to include practical session-authenticated action endpoints as well, including recipe search/details, Recipe Library add/manual add, Meal Planner, Shopping Lists, Displays, Kiosk controls, Let’s Cook, Kitchen Inventory, Settings utilities, Job Status, Backups, and Support Requests. The current route-coverage review also includes AI Recipe Images and browser-session Social Recipe Imports plus newly added Kiosk, Let’s Cook, Recipe multiplier, and Shop With actions. Postman requests use blackcap_postman_token for session-authenticated routes, while API-token routes continue to use blackcap_api_token. The fifteenth pass added explicit Postman setup helpers. The twentieth pass replaces cookie-plus-CSRF Postman usage with a signed 8-hour Postman bearer token issued from the API Tester and audited with source api_tester_postman. Documented-only endpoints, destructive endpoints, user/org lifecycle operations, Database Admin, Data Purge, auth challenge flows, OAuth callbacks, webhooks, static/media routes, and normal page shell routes remain excluded.

The first pass intentionally avoids highly destructive endpoints such as disable, purge, restore, ownership transfer, and broad deletes. Some normal item-level editing and lifecycle endpoints are included because they are useful for API testing, but they still require the API Tester mutating permission and explicit confirmation.

Postman Collection and Environment

The API Tester Postman dialog exports two files:

  • Download Collection exports the curated Blackcap API and session-action Postman collection.
  • Download Environment exports a companion environment containing every variable used by the collection.

The generated collection metadata version is 1.10.5 and is built from the current API Tester registry rather than a separately maintained endpoint list. It therefore inherits registry 1.36 coverage, including the current Recipe Discovery, Plan Meals, and Meal Planner conversion operations that are safe to export. The collection includes generated request bodies, path/query variables, request-description notes, and example successful responses where registry metadata allows a useful sample. The environment initializes base_url from the current browser-visible API Tester URL and leaves secrets as placeholders. When Blackcap is behind stunnel or another TLS terminator, the export prefers the configured external base URL or same-host browser referrer/origin so the value stays https:// instead of the local backend http:// scheme. Use the dialog's Copy Postman Token button to fill blackcap_postman_token when testing session-authenticated Admin/Mobile/UI action routes.

For detailed setup instructions, see:

api-tester.md

Dynamic Typeahead Options

The API Tester exposes read-only option lookups through:

GET /api-tester/options/<source>

These routes require the same logged-in api_tester.view permission and return only values the current session/context is allowed to see. The option service lives in:

inky_admin/services/api_tester_option_service.py

Supported option sources include recipes, displays, kiosk displays, scheduled display assignments, shopping lists, recent jobs, active Let’s Cook sessions, Meal Planner slots, Meal Planner entries, recipe shares, recipe share notifications, recipe share recipient targets, connections, Shop With providers, Shop With store modes, and safe API-token metadata. These are used for fields such as recipe_id, display_id, list_id, entry_id, slot_id, public_id, provider, store_mode, and similar identifiers. Token option metadata includes labels/prefixes only and never returns raw token values. Do not query tables directly from API Tester UI code; add new read-only option sources to the service layer when more typeahead controls are needed.

Structured Request Body Builder

For JSON POST endpoints with a curated request schema, the UI now renders guided body inputs above the raw JSON textarea. Supported schema hints include:

  • enum for dropdowns
  • options_source for typeahead-backed IDs
  • format for date/time/url controls
  • type: boolean, number, and integer controls
  • nested object groups
  • expandable array collections with add/remove rows

Collections render as collapsible sections. Each row is also collapsible, which helps navigate payloads such as display assignments, meal-plan selections, external household-list imports, and Shop With completion results. The raw JSON textarea remains visible and is synchronized from the structured fields, so advanced testers can still review or edit the exact outgoing body.

Structured fields auto-sync into the JSON body as they change. The Rebuild JSON from fields button manually regenerates the JSON from the guided controls if the body looks stale. The Load JSON into fields button parses manually edited JSON and repopulates matching structured controls.

Request Encoding

Each endpoint definition can declare how the tester should submit the request body:

  • json sends application/json through the existing route.
  • form converts the structured body object into form fields, including repeated form values for arrays.
  • multipart is used for routes that need multipart form structure. Curated format: binary fields render safe request-temporary browser file controls and are executable when the endpoint itself is marked safe to run; binary response/download routes can still remain documented-only.
  • query or none indicates that the route does not need a request body.

The UI shows the selected request encoding next to the endpoint metadata. Curl examples now mirror the declared encoding with --data, --data-urlencode, or -F placeholders as appropriate.

Shop With store_mode

store_mode is a provider-specific hint used by the Chrome Extension Shop With flow.

  • For Shipt, it represents the Shipt storefront/slug, such as stores, target, costco, or another configured/free-form Shipt store value.
  • For Amazon, it selects the Amazon shopping surface, such as amazon, amazon_fresh, whole_foods, or amazon_grocery.
  • Providers such as Target, Walmart, and Instacart usually ignore store_mode unless their provider configuration is later enabled for multiple store modes.

The API Tester exposes store_mode as a typeahead backed by configured provider/store-mode metadata. Leaving it blank lets the Chrome Extension endpoint use the provider default or infer the mode from the active provider URL when applicable.

The API Tester registry also includes newer Household List and Recipe Library maintenance actions. Use Pin or Unpin Household Item (POST /shopping-list/{list_id}/manual-item/anchor) to test recurring Household staples without completing the persistent Household List row. Use Bulk Change Recipe Type (POST /api/recipes/bulk-recipe-type) to validate Recipe Library mass type changes and the expected no-cache-rebuild behavior for recipe-type-only metadata edits.

Security Notes

The API Tester is powerful. Keep these rules intact:

  • Do not mount it under /admin.
  • Do not expose it without a logged-in session.
  • Do not allow display tokens or Chrome Extension tokens alone to access /api-tester.
  • Do not store pasted API tokens.
  • Do not persist API Tester tokens server-side. Browser session storage is opt-in and local to the browser session.
  • Do not log raw API tokens, Postman bearer tokens, session cookies, session IDs, OAuth secrets, SMTP passwords, display tokens, or provider secrets. The API Tester can issue a signed 8-hour Postman bearer token to the current logged-in browser for clipboard use, but it must not log or persist the raw token.
  • Keep response display scoped to the selected endpoint. The browser stores each endpoint's last response only in sessionStorage; switching organizations clears that response cache.
  • Keep examples as examples only. Do not use sample values as hidden defaults for request controls unless a field is explicitly context-derived, such as the selected organization id.
  • Do not add arbitrary query parameter forwarding.
  • Do not include destructive endpoints by default.
  • Keep backend route/service permission checks authoritative.
  • Keep all database access in existing service/repository layers.

Adding a New Endpoint

  1. Confirm the route is safe and useful to test.
  2. Add an EndpointDefinition in api_tester_registry_service.py.
  3. Set required_permission to match the underlying feature permission.
  4. Set auth to session, api_token, or either.
  5. Mark read_only=False for any endpoint that changes data.
  6. Add path/query parameters explicitly.
  7. Use example for helper text/placeholders, not for auto-filled default values. Use default_value only when a true default should be submitted. Use value_source="current_org_id" and options_source="organizations" for organization-context fields.
  8. Set request_encoding to match the underlying route: json for JSON APIs, form for form-backed UI routes, multipart only when the route needs multipart data, and none/query when no body is expected.
  9. For request bodies, add enum, options_source, format, nested properties, and array items metadata when available so the structured request builder can render useful controls.
  10. Use options_source="kiosk_displays" for kiosk-only display IDs, options_source="displays" for general display IDs, options_source="recipes" for recipe IDs, options_source="meal_plan_slots" for Meal Planner slots, and options_source="meal_plan_entries" for Meal Planner entries.
  11. Write descriptions as two short sentences when possible. Keep them focused on what the endpoint is for, what workflow it supports, or what it helps troubleshoot. Do not repeat authentication requirements in the description because the UI renders that separately. If a description is short, the registry service adds a second purpose/context sentence in the public spec.
  12. Test as System Admin and, if applicable, Org Admin.
  13. Confirm the endpoint’s Postman behavior. Safe, runnable API Tester endpoints—including ordinary session-authenticated APIs—export by default. Set postman_export=False only when the endpoint is not reasonable to call from Postman (for example, a browser callback, webhook, binary viewer, destructive/admin-only maintenance surface, or other explicit exclusion).
  14. Confirm no secrets appear in the response viewer, Postman collection, or audit log.

Restart

After deploying these files, restart the Admin service:

sudo systemctl restart inky_admin.service
sudo systemctl status inky_admin.service --no-pager

Testing Checklist

  • /api-tester loads for authorized logged-in users.
  • /api-tester is not under /admin.
  • /api-tester/spec requires login and api_tester.view.
  • /api-tester/execute requires login, api_tester.view, and CSRF.
  • Lower roles cannot access the tester by default.
  • Spec output is filtered by current permissions.
  • Read-only session endpoints run successfully.
  • Current organization context is respected.
  • System Admin can switch organization context from /api-tester.
  • Multi-organization Org Admin users can switch among their allowed organizations.
  • Switching context reloads /api-tester/spec and clears endpoint response cache.
  • Optional org_id fields show the selected real organization id, not org_....
  • System Admin/multi-org users get typeahead organization choices where an endpoint accepts org_id.
  • Recipe, display, shopping list, job, and similar identifier fields use context-aware typeahead options where available.
  • Kiosk endpoints use kiosk-display typeahead values only.
  • Shop With provider and store-mode fields use configured provider/store-mode typeahead options.
  • /api-tester/options/<source> returns safe option values and does not expose raw token values.
  • /api-tester/postman-collection downloads a valid Postman v2.1 collection.
  • /api-tester/postman-environment downloads a valid companion Postman environment with the current browser-visible base_url filled in and secret values left as placeholders.
  • The Postman collection and environment use variables/placeholders and do not include real API tokens, Postman bearer tokens, client tokens, or share tokens.
  • The Postman collection includes API-token endpoints and useful session-authenticated action endpoints while using placeholder variables for blackcap_api_token and blackcap_postman_token.
  • The API Tester Postman button opens a setup dialog instead of showing Postman setup controls in the main sidebar.
  • The setup dialog offers both Download Collection and Download Environment actions.
  • The setup dialog can issue and copy an 8-hour Postman bearer token for the blackcap_postman_token Postman variable after an explicit button click.
  • Postman token audit events use source api_tester_postman.
  • The Postman collection excludes documented-only, destructive, user/org lifecycle, Database Admin, Data Purge, OAuth callback, webhook, static/media, and page-shell routes.
  • Searching for add recipe api, create recipe, or /api/recipes/add finds the Chrome Extension Add Recipe API endpoint.
  • Searching for recipe library add, manual recipe, /add-recipe, or /manual-recipe finds the session-authenticated Recipe Library add flows.
  • Endpoint groups are sorted alphabetically and endpoints within each group are sorted by display name.
  • Long endpoint groups keep their group header visible while scrolling until the next group header takes over.
  • POST endpoints with curated schemas show guided inputs, dropdowns, typeaheads, and expandable collection rows.
  • Form-backed endpoints show request encoding as form and submit through form data rather than JSON.
  • Settings endpoints are visible only to users with the matching settings/configuration permissions.
  • Rebuild JSON from fields and Load JSON into fields behave as expected after manual JSON edits.
  • Non-context request controls start blank while still showing helper examples.
  • Response search is visible whenever a response is shown.
  • Click inside a response body and press Ctrl+F/Cmd+F to focus the response search box.
  • API-token endpoints require a pasted token.
  • API-token endpoints can optionally reuse a token remembered in browser session storage.
  • The Chrome Extension token handoff works only when the extension is installed, configured for the current Blackcap host, and reloaded with the supporting content-script version.
  • Chrome does not autofill the endpoint search box with login data.
  • Chrome does not autofill the API token box with the account password.
  • Invalid/revoked tokens show clean errors.
  • Curl examples use <API_TOKEN>, never the real token.
  • Mutating endpoints require the confirmation checkbox.
  • Mutating endpoints require api_tester.execute_mutating.
  • Documented-only endpoints show in the registry but cannot be executed directly from the tester.
  • Curated multipart upload endpoints use request-temporary browser file attachments; binary response/preview endpoints remain documented-only until a safe binary response flow is added.
  • No highly destructive endpoints are exposed by default.
  • Admin UI, Mobile UI, Kiosk, and Chrome Extension behavior remain unchanged.
  • No new direct SQL calls were introduced by the API Tester implementation.

API Tester button styling

API Tester action buttons should follow the Blackcap style of using concise emoji cues where they improve scanability. Endpoint list buttons still prioritize method/path readability, while action buttons such as Postman, Reload, Try It, Load Example, Copy Postman Token, Clear, and structured-body helpers include visible emoji labels.

Voice Assistant testing

The API Tester exposes Voice Assistant Test → Alexa Integration Status and Voice Assistant Test → Google Home Integration Status so platform OAuth/client status, HTTPS posture, and provider URLs can be copied into the provider consoles. Configure credentials first in Platform → Voice Assistant Providers. Alexa uses the generated Alexa OAuth Client ID/Secret for both the ask Blackcap custom skill and the Alexa Smart Home skill. Google Home uses its own generated OAuth Client ID/Secret for Cloud-to-cloud account linking.

Provider-facing fulfillment endpoints are not general API Tester endpoints:

  • /voice/alexa/skill expects signed Alexa Custom Skill requests.
  • /voice/alexa/smarthome is normally called by the AWS Lambda relay for Alexa Smart Home directives.
  • /voice/google-home/fulfillment expects Google Home Cloud-to-cloud OAuth bearer tokens and intent payloads.

Use Voice Assistant Test → Internal Voice Command Test for safe service-layer command coverage. It exercises the provider-neutral command service used by all three surfaces: ask Blackcap, Alexa Smart Home, and Google Home. The endpoint now covers the full current command set: start/end cooking, next/previous step, start/pause/resume/stop/cancel timer, add/subtract one or five minutes, and timer status.

Recommended quick API Tester checks after voice-assistant changes:

  1. Run START_LETS_COOK against a known display.
  2. Run NEXT_STEP and PREVIOUS_STEP against the same display.
  3. Run START_TIMER, PAUSE_TIMER, and RESUME_TIMER.
  4. Run ADD_TIMER_MINUTES with minutes=1 and SUBTRACT_TIMER_MINUTES with minutes=1.
  5. Run END_LETS_COOK.
  6. Verify the command log in Database Admin records the provider, skill type, endpoint id when provided, display resolution source, status, and response summary without raw provider payloads.

Let’s Cook voice takeover endpoint

The API Tester includes Show Entire Recipe for Voice Session under Let’s Cook. It posts to /api/lets-cook/sessions/{session_id}/show-entire-recipe and exercises the same per-session render override used by Admin/Mobile/Kiosk/touch receiver takeover controls. The action preserves the active session, step/ingredient completion state, timers, and display default settings.

Database Admin / SQL Console coverage

The Database Admin category now documents the in-page tab endpoints used by the Database page shell:

  • GET /admin/database/api/tabs/resources
  • GET /admin/database/api/resource-counts
  • GET /admin/database/api/tabs/maintenance
  • POST /admin/database/api/tabs/maintenance/{action_key}
  • GET /admin/database/api/tabs/sql
  • POST /admin/database/api/tabs/sql

These fragment endpoints should be used when testing tab behavior because switching Resources, Maintenance, and SQL Console from the UI should not reload the full Database page. Resource counts and overview metrics are loaded separately after the shell renders. The resource-count example includes counts_complete, failed_resources, per-resource exists/error fields, and the aggregate header metrics so a partial count failure can be diagnosed without treating every resource as failed.

Maintenance action inputs use the dynamic database_maintenance_actions option source. It returns only actions supported by the active database provider and permitted for the current user. SQLite testers therefore see integrity, quick-check, WAL, vacuum, and analyze actions as applicable; PostgreSQL testers see connectivity and analyze actions rather than SQLite file operations.

Database resource column preferences use POST /admin/database/resources/{resource_key}/columns. The form accepts repeated visible_columns values plus optional repeated column_order values. column_order may include both visible and hidden allowed columns so a hidden column keeps its preferred position if it is shown again later. The route rejects/discards fields outside the resource's allowed Database Admin columns. Omitting column_order preserves the user's existing saved order when possible.

The SQL Console entries document the current guardrails:

  • SQL execution is System Admin only.
  • Submit exactly one read-only statement using the active SQLite or PostgreSQL provider's supported syntax.
  • WITH / CTE statements are blocked; use joins or derived subqueries instead.
  • limit is the rows-per-page value when the SQL statement does not include its own LIMIT.
  • Organization-scoped tables are allowed, but raw SQL is not automatically scoped to the current organization.
  • Tables with protected fields can be queried and joined, but protected fields cannot be selected; avoid SELECT * and alias.* for those tables.

The schema helper endpoints are also documented:

  • GET /admin/database/api/sql-console/schema returns the active provider object plus table and safe-column metadata for autocomplete.
  • GET /admin/database/api/sql-console/schema/{table_name}/samples lazy-loads org-scoped example values for one table at a time.
  • GET /admin/database/sql/schema-export downloads the Markdown schema brief for LLM or AI-assisted query drafting.
  • GET /admin/database/api/sql-console/ai/options returns the enabled Create SQL Query Quality Profiles plus Organization/Personal AI Seed availability.
  • POST /admin/database/api/sql-console/ai/jobs creates a durable asynchronous AI SQL create/modify job. It requires confirm=true plus explicit Quality Profile/Seed funding selection. existing_sql switches the request to modify mode, and optional previous_job_id links a prior completed SQL AI turn so compatible OpenAI/Gemini profiles can continue provider-side conversation state instead of retransmitting the full schema. When continuation is unavailable Blackcap safely resends the complete schema/request context. It never executes the generated SQL. API Tester can execute it after its normal mutation confirmation, but Transactional Multi API excludes it because provider/Seed side effects cannot be rolled back.
  • GET /admin/database/api/sql-console/ai/jobs/{job_id} polls the durable job until the validated read-only SQL is ready for the SQL Console editor and reports create/modify mode, chain/iteration linkage, prior job, and whether provider-side conversation state was reused.

Create/Modify SQL Query is intentionally a draft-only workflow: the AI result is validated as one read-only SELECT, then returned to the editor for System Admin review. Running it remains a separate explicit Run Query action. AI Usage / What Happened records original/new request context, current/generated SQL, chain/iteration metadata, and provider-context reuse. The SQL Console's 🧹 Clear action resets the local editor/iteration convenience history; it does not erase AI Usage audit history.

The schema metadata example includes provider_name, backend_name, sql_dialect, dialect guidance, and the provider-specific export filename. This makes it possible to confirm that the tester and SQL editor are using the same active backend before running a query.

The schema export endpoint is safe to download, but the tester marks it as a file/diagnostic endpoint because it returns Markdown rather than JSON. The downloaded filename and opening guidance identify the active SQLite or PostgreSQL provider and SQL dialect so an LLM does not generate syntax for the wrong backend. PostgreSQL exports also use the live physical column types as the source of truth: integer-backed flags use 1/0, native booleans use TRUE/FALSE, text-backed timestamps and JSON require safe casts, matching join types should not be cast unnecessarily, and UNION/UNION ALL output types must align. The export also includes production-query guidance that excludes regression test and diagnostic clone organizations with regression_test_organizations and regression_diagnostic_clones, plus display-assignment guidance that uses display_content_assignments instead of app_state JSON.

Meal-plan, Recipe Sharing, and display-deletion additions

The curated registry includes these workflow-specific entries:

  • Recipe Add to Meal Plan Options — GET /api/meal-planner/recipe-add-options/{recipe_id} with optional date and slot_id query parameters. The response exposes active slots, slot-specific people served, the selected multiplier, and the ordered recipe-specific multiplier choices used by the Recipe Library popup.
  • Add Home Recipe to Other Date — POST /api/meal-planner/home-future-entry. plan_date must be after tomorrow in the organization time zone. This is a mutating, CSRF-protected entry and requires API Tester mutation permission.
  • Outbound Recipe Share Links — GET /api/recipe-shares/outbound/active with status=active|expired|completed. The registry name reflects that the endpoint now serves history filters rather than only active links.
  • Delete Display — POST /admin/displays/{display_id}/delete, documented as destructive and not safe to run from the tester. The optional replacement_default_display_id is required when deleting the current default. The production route still enforces organization scope, only-display protection, active Let’s Cook protection, assignment cleanup, and replacement-default validation.

Mass Refresh Cache and Delete on Recipe Library intentionally reuse the existing single-recipe endpoints and therefore do not add separate bulk API Tester definitions:

  • POST /refresh-recipe/{recipe_id}
  • POST /delete-recipe/{recipe_id}

MFA setup/challenge routes remain excluded because they operate on incomplete-login session state and authentication secrets. Existing policy/reset administration entries provide the appropriate tester coverage.

Home dashboard and display assignment coverage

The Displays category now documents the shared assignment routes used by Home, the Displays page, and Display Details:

  • Assign Display Content (POST /api/displays/assign-content) supports recipe, menu, meal-plan, and attached local e-ink Client assignment. Client is valid only for the one attached local e-ink display, only as immediate current content, and cannot be scheduled or made default. For meal plans, settings.view can be day, today_tomorrow, week, or month.
  • Return Displays to Default (POST /api/displays/return-default) returns one or more displays to their configured default content.
  • Start Let’s Cook Session (POST /api/lets-cook/sessions) is the tester entry point for Assign Content Let’s Cook behavior. Use display_id: "here" to create a local/Admin-console cooking session, or pass a display id to start Let’s Cook for a display. A remote Raspberry Pi client session is allowed even when its fast preview watcher is disabled or stopped; the response then includes warning and warnings fields explaining that later step, ingredient, and timer updates may be delayed.

Example Today & Tomorrow meal-plan assignment:

{
  "display_ids": ["disp_..."],
  "content_mode": "current_meal_plan",
  "action": "show_now",
  "settings": {
    "view": "today_tomorrow",
    "anchor_policy": "current_day"
  }
}

Example Return to Default request:

{
  "display_ids": ["disp_..."]
}

Example Here Let’s Cook request:

{
  "recipe_id": "recipe_...",
  "display_id": "here",
  "source": "api_tester",
  "multiplier": 1,
  "restore_display_content": true
}

System audit background actions

The API Tester registry includes the System-page background actions for Direct SQL Audit, Database Parity Audit, safe parity repair, and compact audit-job status polling. The parity audit target remains read-only; the repair endpoint requires the explicit repair-safe-database-gaps confirmation value and is not marked safe to run automatically.

Attached e-ink Client API coverage

The Remote Display Client category documents the full pull-client lifecycle:

  • POST /api/display-client/pair exchanges a short-lived code for a durable client token.
  • GET /api/display-client/state returns the remote display state without embedding the token in the preview URL. It also returns normal_pull_interval_seconds and advertises a 5-second pull_interval_seconds while active_lets_cook=true; normal content returns to the configured interval, 30 seconds by default.
  • GET /api/display-client/preview is documented-only because it returns binary image data.
  • POST /api/display-client/heartbeat accepts physical-display acknowledgement metadata such as the last preview displayed, panel update time, grayscale mode, and four-level panel capability.
  • POST /api/display-client/unlink revokes the presented durable client token. It is destructive and requires API Tester mutation permission.

The attached Pi display’s Link/Relink/Unlink Admin forms are intentionally not separate executable API Tester endpoints; they manage an encrypted local token and incomplete pairing state through the Display Details workflow.

Kitchen Inventory archive and restore

The curated registry documents Admin and Mobile Kitchen Inventory archive/restore routes. Archive/delete entries require inventory.delete, current-organization scope, and CSRF; they are marked documented-only/destructive so the API Tester cannot accidentally delete a real item. The archive examples show that deleting an on-hand item returns status=archived and is_on_hand=false, while preserving its pre-delete on-hand state internally. Restore entries reuse the same public inventory ID and return an item that was previously on hand to status=active and is_on_hand=true.

The generic Update Database Resource Row entry also documents the Database Admin lifecycle safe edit. For inventory_items, status may transition only between active and archived; the request additionally requires inventory.delete, is organization-scoped, and is routed through the Kitchen Inventory service rather than written directly. The route remains documented-only because arbitrary resource editing requires resource-specific safeguards.

AI Usage and AI Seed administration

The curated AI Usage category exposes authenticated read APIs for the completed AI administration experience:

  • AI Usage Report — GET /api/admin/ai/usage
  • View Support Chat History — GET /api/admin/ai/usage/support-chat/{session_id}
  • AI Usage Quality Profile Summary — GET /api/admin/ai/usage/profile-summary/{use_case_key} (System Admin only)
  • AI Usage What Happened — GET /api/admin/ai/usage/what-happened/{event_id} for Recipe Photo, Social Recipe, Inventory Photo Analysis, and Plan Meal evidence
  • AI Usage What Happened Photo Artifact — GET /api/admin/ai/usage/what-happened/{event_id}/artifact/{artifact_index} for retained Recipe Photo or Inventory Photo Analysis inputs (documented binary route; not executable in the text/JSON tester and not exported to Postman)
  • View Retained Generated Image — GET /api/admin/ai/usage/generated-image/{event_id} (documented binary route; not executable in the text/JSON tester and not exported to Postman)
  • Download AI Provider Billing Reconciliation CSV — GET /admin/ai/usage/reconciliation.csv (System Admin only)
  • Organization AI Seed Balance — GET /admin/ai/organizations/{organization_id}/drupeletes
  • Organization AI Seed Recent Adjustments — GET /admin/ai/organizations/{organization_id}/drupeletes/adjustments
  • Personal AI Seed Balance — GET /admin/ai/users/{user_id}/drupeletes

The JSON usage report uses the same authorization, filters, server-side paging, grouped use-case summaries, Support Chat effectiveness summary, and organization/user scope as the AI Usage page. Org Admin responses omit provider-owned correlation identifiers, detailed provider token usage, provider-cost/billing diagnostics, provider usage payloads, and provider response metadata. System Admin responses may include provider_request_id, the derived provider_display_id / provider_display_id_kind used by the UI, user-friendly failure_reason, and the protected provider-response correlation recovered from the linked AI Job when needed. Provider credentials and raw prompts are never returned.

The Support Chat history entry exercises the same organization-authorized, user-visible transcript data used by the 🛟 AI Usage action. A purged transcript returns history_available=false rather than exposing deleted content. AI Usage What Happened returns the same organization-authorized Recipe Photo, Social Recipe, Inventory Photo Analysis, or Plan Meal evidence used by the 🔎 row action; Org Admin callers never receive estimated provider cost. AI Usage Quality Profile Summary is System Admin-only and returns the profile's current AI Seed price plus historical average latency and estimated provider cost while intentionally ignoring the report's current profile filter. The generated-image and Recipe Photo/Inventory Photo evidence artifact entries remain in the registry for route coverage, but their binary responses are intentionally not sent to the current text/JSON API Tester response viewer.

The reconciliation endpoint is intentionally visible only to System Admins and returns CSV. Balance adjustment writes are not marked as safe API Tester operations because they create audited financial-style ledger changes. Use Organizations or Users for normal adjustments.

Useful report query parameters include organization_id, date_from, date_to, provider_type, provider_connection_id, use_case_key, profile_key, user_id, outcome, selected_source, estimated_cost_min, estimated_cost_max, sort, page, and per_page. Supported operational sorts include created-time ordering plus latency and estimated-cost low/high ordering. Estimated-cost filtering/sorting is System Admin-only. organization_id=all means All Organizations for System Admin or All My Organizations for an authorized multi-organization Org Admin.

Postman usage

Blackcap can export a Postman collection and companion environment from the logged-in API Tester at /api-tester. The collection is generated from the curated API Tester registry, so it avoids documented-only routes, destructive routes, callback/webhook flows, static assets, normal page shells, and other routes that do not make sense to call directly from Postman.

Download from the API Tester

  1. Log in to Blackcap.
  2. Open /api-tester.
  3. Click the Postman button in the sidebar.
  4. Download the collection with Download Collection.
  5. Download the environment with Download Environment.
  6. Import both files into Postman.
  7. Select the imported Blackcap API and Session Actions Environment environment before running requests.

The collection contains request bodies, path/query variables, request descriptions, and example responses where the API Tester registry has enough metadata to generate them safely.

Environment variables

The environment file defines all variables used by the collection. The base_url value is filled in from the browser-visible API Tester URL at download time; secret values remain placeholders until you paste the values you need. When Blackcap is behind stunnel or another TLS terminator, the export prefers the configured external base URL or same-host browser referrer/origin so the value stays https:// instead of the local backend http:// scheme.

Common variables:

Variable Purpose
base_url Base Blackcap URL, such as https://blackcap.example.com
blackcap_api_token Chrome Extension/API-token value for API-token endpoints
blackcap_postman_token 8-hour bearer token copied from the API Tester for session-authenticated endpoints
recipe_id Recipe ID or slug to use in recipe endpoints
display_id Display ID to use in display endpoints
list_id Shopping list ID to use in shopping-list endpoints
provider External shopping provider key, such as Google Keep, Amazon/Alexa, Target, Walmart, or Instacart provider values
store_mode Optional provider-specific mode; leave blank unless testing a provider that needs it
client_token / pairing_token Remote Display Client token values
recipe_share_public_id / recipe_share_token Recipe share import/export token values

API-token authentication

Chrome Extension and external API-token endpoints use:

Authorization: Bearer {{blackcap_api_token}}

Use an existing Blackcap API token from the Admin UI or Chrome Extension configuration. Do not paste this token into request descriptions or committed files.

API Tester session-token authentication

Many Admin, Mobile, Recipe Library, Meal Planner, Shopping List, and Settings routes require a logged-in Blackcap user context. In Postman, these routes use an API Tester-issued bearer token instead of copying the browser session cookie and CSRF token:

Authorization: Bearer {{blackcap_postman_token}}

To copy the Postman token:

  1. Open /api-tester while logged in.
  2. Select the organization context you want the token to use.
  3. Click Postman.
  4. Click Copy Postman Token and paste it into the blackcap_postman_token environment variable.

The token lasts for 8 hours, is scoped to the current user and organization context, and should completely replace the environment variable value. Treat it like a password and clear it when you finish testing.

AI Usage collection folder

For users who can see the corresponding API Tester entries, the generated Postman collection includes an AI Usage folder with the safe read-only reporting, retained Support Chat transcript, and balance-inspection endpoints:

  • GET /api/admin/ai/usage
  • GET /api/admin/ai/usage/support-chat/{session_id}
  • GET /api/admin/ai/usage/profile-summary/{use_case_key} for System Admins
  • GET /api/admin/ai/usage/what-happened/{event_id} for authorized Recipe Photo/Social Recipe evidence
  • GET /admin/ai/usage/reconciliation.csv for System Admins
  • GET /admin/ai/organizations/{organization_id}/drupeletes
  • GET /admin/ai/organizations/{organization_id}/drupeletes/adjustments
  • GET /admin/ai/users/{user_id}/drupeletes

The generated-image and retained Recipe Photo artifact binary routes are intentionally excluded from Postman because their primary purpose is the authenticated in-product viewers and the API Tester/Postman metadata flow is text/JSON oriented. The copied Postman token preserves the signed-in user's permissions and organization context. Provider IDs (request ID first, durable response/message ID fallback), provider-reported token counts, profile cost comparisons, and estimated provider-cost diagnostics remain System Admin-only. The collection intentionally omits AI Seed adjustment writes because those operations change audited balances.

Kitchen Inventory and Put Away endpoints

The curated registry includes the quantity-aware Inventory actions used by Mobile/support testing: add physical Package, set remaining amount, resolve/scan Product, transient barcode-frame decode, stage a temporary Product photo for barcode/Product/fullness review, stage a separate multi-item Kitchen Inventory Overview photo, apply/discard reviewed captures, query Expected Runout, Put Away disposition/location/Product reconciliation, and the asynchronous Product/Overview Photo AI Analysis submit/status/review endpoints. Multipart photo/frame entries accept executable request-temporary file attachments in API Tester; normal permission, organization, CSRF/session/Postman-token, upload-size, and mutation-confirmation rules still apply. Raw barcode camera frames are never retained by these endpoints. Product Photo and Overview Photo AI submit confirmation represents the displayed AI Seed use; provider/image-retention mechanics are not part of the confirmation UI. Multipart endpoints are intentionally excluded from Multi API, while database-only Inventory mutations such as Add Package, Set Remaining, and Update Product Details are eligible for transactional Multi API execution.

The registry also exposes the platform Ingredient Density catalog through list/add/save JSON endpoints. These endpoints are eligible for Multi API (subject to System Admin permissions), so density configuration can be tested transactionally. Ingredient-density conversion is used when Let’s Cook consumption crosses volume and weight measurement families; same-family unit conversion remains deterministic and does not consult density.

Made It API descriptions reflect the shared Recipe-level state: reading returns the currently stored Recipe feedback and an authorized multipart update edits that same Recipe record, including rating, notes, cleanup feedback, and optional photo. Made It multipart updates are executable in API Tester but excluded from Multi API because they may carry a file attachment.

Request examples

The generated collection includes request examples in the actual Postman request definitions:

  • path variables are converted to Postman variables such as {{recipe_id}} and {{display_id}}
  • useful query parameters are included but optional ones may be disabled by default
  • JSON endpoints include sample JSON bodies when the registry has a request schema or example payload
  • form-backed routes include x-www-form-urlencoded fields
  • multipart routes include non-file field metadata and file placeholders where applicable
  • saved example responses are included to show the expected shape of successful responses

If a request body is too broad for a safe generic example, use the API Tester structured request builder first, then copy the resulting JSON/form values into Postman.

Why Basic Auth is not used

Blackcap's session-authenticated routes rely on the normal login session for user identity, effective role, organization context, MFA/trusted-browser state, session timeout behavior, CSRF protection, and permission checks. Basic Auth would require a separate authentication layer and could accidentally bypass or duplicate important behavior.

Use Chrome Extension API tokens for Chrome Extension/external routes and the copied blackcap_postman_token for session-authenticated Admin/Mobile/UI action routes.

API Tester Postman token

The API Tester-issued Postman token is a Blackcap-specific token type. It is not Basic Auth and it is not the same as the Chrome Extension API token. It is signed with the app secret, valid for 8 hours, scoped to the current logged-in user and selected organization context, and audited with source api_tester_postman.

A Postman token is intended for support/developer testing of session-authenticated routes from Postman. It should not be used by the Chrome Extension, display clients, or long-running external integrations.

Safe usage notes

  • Do not commit exported environments after filling in secrets.
  • Clear blackcap_postman_token and blackcap_api_token when finished.
  • Prefer test recipes, displays, and shopping lists when running mutating requests.
  • Avoid running collection requests in bulk against a production organization unless you have reviewed the request bodies and variables.
  • Use the in-browser API Tester first for complex mutating requests because it has stronger guided inputs, context-aware typeaheads, and explicit mutation confirmation.

Expand and collapse endpoint groups

API Tester endpoint groups remain expanded on every fresh page load, preserving the existing default. Compact Expand All and Collapse All controls operate on the <details> groups that are actually rendered for the current role/configuration; there is no separate hard-coded group-id list. Individual groups continue to work after either bulk action, and aria-expanded is synchronized for keyboard and assistive-technology users.

Plan Meal and Meal-level Let’s Cook APIs

API Tester includes the normal authenticated product APIs for the Meal lifecycle:

  • read the rich Meal Slot summary, including custom Meal identity/image, entries, and current AI-plan summary;
  • set/reset one dated Meal Slot's people-served override or apply people-served values in bulk;
  • read the saved Meal Slot AI plan;
  • queue create/replan of the saved Meal Slot AI plan and poll its asynchronous AI job status;
  • delete only the saved AI Meal Plan;
  • preview/start deterministic sequential Let’s Cook Meal;
  • preview/start an already saved planned Meal;
  • finish a Meal session normally while Meal Items remain passive header-only side context.

Move Entry and Move Slot request schemas also expose recalculate_multipliers so API Tester can exercise the same destination people-served behavior as drag/drop. Manual multiplier overrides remain protected. A same-Meal-Slot whole-Meal date move can carry a current AI Meal Plan when the destination is empty/replaced and recalculation does not change serving inputs; a merge, different Meal Slot, or material serving change follows the normal invalidation contract.

The provider-backed Plan Meal POST additionally requires confirm=true to acknowledge the displayed AI Seed cost and sending the trusted Meal Slot Recipe details to the selected AI provider. The POST returns 202 with an AI job; clients poll Plan Meal Job Status until the job reaches completed or failed, then read the saved plan normally. This AI-specific consent is separate from API Tester’s normal mutating-call confirmation. Meal Planner mutation schemas expose confirm_plan_invalidation where a current saved plan can be made stale. A client must first receive the protected-change conflict and then explicitly resubmit with confirmation; the server does not infer consent and does not silently regenerate a plan.

API Tester also exposes the presentation-only whole-Meal identity actions: Rename Meal, multipart Upload Meal Image, AI Meal Image Options, and Generate AI Meal Image. AI Meal Image generation deliberately reuses the configured Manual Recipe Image Generation Quality Profiles and Organization/Personal AI Seed balances; profile_key is therefore the actual configured profile key returned by the options endpoint rather than a fixed low/medium/high enum. It queues the same asynchronous image-job lifecycle and is reviewed/accepted through the existing AI image job endpoints. Renaming or replacing a Meal image does not invalidate or regenerate an AI Meal Plan because neither changes trusted cooking content.

Meal-level component_choices are also accepted when starting a current saved AI Meal Plan. A final Let’s Cook choice of already prepared / keep omits that Component Recipe from execution without regenerating the saved AI plan; a make choice can supply the final batch multiplier. Sequential Meal starts additionally support placement_index, representing the visual insertion point among the associated Recipe-name anchors. These are final cooking choices; Shopping can persist provisional per-Meal choices earlier, while Plan Meal normally schedules unresolved Components conservatively rather than forcing a make/keep decision.

The permission-checked GET /admin/meal-planner/meal-image response and GET /admin/meal-planner/review/pdf response are binary media/download endpoints. They remain intentionally outside the generic API Tester execution surface; API Tester covers the JSON/multipart control operations while normal Meal Planner/Review UI and regression coverage validate the protected image/PDF downloads.

The existing Data Purge → Preview Data Purge / Run Selected Data Purge operations cover every manually selectable Data Cleanup group, including Meal Plans, AI Operational History, Support Chat History, Social Recipe Import Data, and Regression Test Organization Markers. The form contract mirrors the real Data Cleanup routes: preview sends content_type plus repeated selected_ids; the destructive run sends those same fields plus the exact typed confirm_text (PURGE N RECORDS). Use the opaque IDs shown by Data Cleanup rather than constructing them by hand. AI terminal-job IDs are represented as job:<job_id>, while the safe detached-accounting aggregate uses shared-accounting.

Run Scheduled Data Purge Now also exercises the automatic retention side: terminal AI operational history follows each use case's AI Data Retention, Support Chat terminal graphs are removed when due, old Social Recipe Import evidence is compacted, and orphaned Regression Test Organization markers are pruned after their real environment/run protection is gone. These destructive Data Cleanup operations remain intentionally excluded from Multi API; Multi API is for transaction-safe database operations, not filesystem/evidence cleanup or cross-domain retention jobs. The Support Chat AI Usage transcript endpoint may return 200 with history_available=false when a terminal chat was purged early but its AI Usage correlation is still inside retention.

Adapt Recipe metadata visibility

The canonical adaptation detail lookup (GET /api/recipes/{recipe_id}/adaptation-preferences) returns the saved dietary selections and request from the organization-scoped Recipe record. It is also the read model used by both editing dialogs, even after a Recipe cache rebuild. The existing Recipe Save workflows update these fields; no separate Save button or cache regeneration is required when only adaptation details change. GET /api/recipes/{recipe_id}/quick-view presents the same saved details in a read-only collapsed panel.

Adapt Recipe submission tracking and review cancellation

Adapt Recipe exposes a read-only GET /api/recipes/{recipe_id}/adapt/jobs/lookup?key={idempotency_key} operation to report the job created by a still-pending generation POST. It is organization-, user-, recipe- and use-case-scoped and never generates a recipe or reserves AI Seeds. The dialog continues polling the normal durable job endpoint after the job ID is known. The progress steps distinguish Seed reservation, recipe preparation, provider submission, adaptation, validation and review.

The ↩️ Cancel control is available only after AI generation completes and an unsaved review appears. It finalizes/discards the review through the existing idempotent review-finalization logic, without attempting to interrupt or refund an ongoing provider operation. During generation, ✖ Close is the available way to leave the dialog while allowing the durable job to continue.

Original Recipe and Combine endpoints (0.7.3-alpha development)

New authenticated Recipe endpoints include GET /api/recipes/ai-original/options, POST /api/recipes/ai-original/jobs, GET /api/recipes/ai-original/jobs/lookup, POST /api/recipes/<recipe_id>/adapt/compare, POST /api/recipes/adapt/jobs/<job_id>/combine and POST /api/recipes/adapt/jobs/<job_id>/comparison-cancel. They require recipes.create permissions and follow the existing JSON/CSRF conventions. Job polling, review and saving use the existing Adapt Recipe job routes. The second confirmation requires explicit confirm: true for a new generated Recipe. AI-created Recipe IDs are based on the final saved name (with organization-local collision suffixes), and AI-authored recipes carry no imported webpage source URL or View Source link. Endpoint registration and schema tests are covered locally; interactive API Tester execution still requires validation on a deployed installation.

On this page