API Architecture

Audience: Developer, System Admin, Support Related: Api Tester · Security And Scoping · Architecture

Blackcap APIs are organized by feature blueprints and registered in the API Tester registry. Authentication may use a browser session, a user-owned API Token, provider-specific linking credentials, or signed provider requests depending on the endpoint.

New APIs must enforce permissions and organization scope in the service layer, sanitize responses and diagnostics, use centralized database access, document idempotency and error behavior, and add focused tests and API Tester metadata.

API eligibility and orchestration

• API Tester endpoints assessed: 346
• Runnable API Tester endpoints: 272
• Multi API eligible: 155 (75 reads, 80 verified mutations)
• Excluded: 191

Eligibility is intentionally limited to safe reads and mutations verified to use Blackcap’s centralized app-database transaction. Email, browser/display control, file generation/upload, background jobs, credential rotation, external-system calls, and destructive operations are excluded because those effects cannot be rolled back with SQLite/PostgreSQL.

Exclusion summary

• 99: Mutation has non-database side effects or is not verified rollback-safe
• 73: Disabled or documented-only in API Tester
• 15: API-token-only; cannot inherit outer session transaction
• 2: Self/context-changing endpoint
• 2: Destructive endpoint

API Orchestration

Endpoint ID	Method	Path	Multi API	Assessment
multi_api_transaction	POST	/api/multi	Excluded	Self/context-changing endpoint

API Tester

Endpoint ID	Method	Path	Multi API	Assessment
api_tester_options	GET	/api-tester/options/{source}	Eligible	Safe read operation

Admin Pages

Endpoint ID	Method	Path	Multi API	Assessment
admin_tools_emojis_page	GET	/admin/tools/emojis	Excluded	Disabled or documented-only in API Tester
current_organization_config_pull_panel	GET	/admin/organization/config-pull-panel	Excluded	Disabled or documented-only in API Tester
organizations_config_push_panel	GET	/admin/organizations/config-push-panel	Excluded	Disabled or documented-only in API Tester

Auth Providers

Endpoint ID	Method	Path	Multi API	Assessment
auth_provider_sync_default_login_providers	POST	/admin/platform/auth-providers/sync-default-login-providers	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Backups

Endpoint ID	Method	Path	Multi API	Assessment
backup_disconnect_dropbox	POST	/cloud-backup/dropbox/disconnect	Excluded	Disabled or documented-only in API Tester
backup_disconnect_google_drive	POST	/cloud-backup/google/disconnect	Excluded	Disabled or documented-only in API Tester
backup_download	GET	/cloud-backup/download	Excluded	Disabled or documented-only in API Tester
backup_restore	POST	/cloud-backup/restore	Excluded	Mutation has non-database side effects or is not verified rollback-safe
backup_retention_cleanup	POST	/cloud-backup/retention-cleanup	Excluded	Mutation has non-database side effects or is not verified rollback-safe
backup_run_now	POST	/cloud-backup/backup-now	Excluded	Mutation has non-database side effects or is not verified rollback-safe
cloud_backup_connection_test	POST	/cloud-backup/test/{provider}	Eligible	Safe read operation
cloud_backup_download_check	GET	/cloud-backup/download-check	Eligible	Safe read operation
cloud_backup_status	GET	/cloud-backup/status	Eligible	Safe read operation

Chrome Extension

Endpoint ID	Method	Path	Multi API	Assessment
assisted_shopping_already_have	POST	/api/shopping/assisted/{list_id}/already-have	Excluded	API-token-only; cannot inherit outer session transaction
assisted_shopping_complete	POST	/api/shopping/assisted/{list_id}/complete	Excluded	API-token-only; cannot inherit outer session transaction
assisted_shopping_context	GET	/api/shopping/assisted/{list_id}	Excluded	API-token-only; cannot inherit outer session transaction
assisted_shopping_review	GET	/api/shopping/assisted/{list_id}/review	Excluded	API-token-only; cannot inherit outer session transaction
assisted_shopping_review_complete	POST	/api/shopping/assisted/{list_id}/review/complete	Excluded	API-token-only; cannot inherit outer session transaction
assisted_shopping_review_reshop	POST	/api/shopping/assisted/{list_id}/review/reshop	Excluded	API-token-only; cannot inherit outer session transaction
assisted_shopping_review_uncheck	POST	/api/shopping/assisted/{list_id}/review/uncheck	Excluded	API-token-only; cannot inherit outer session transaction
extension_add_recipe_url	POST	/api/recipes/add	Excluded	API-token-only; cannot inherit outer session transaction
extension_capture_recipe	POST	/api/extension/recipes/capture	Excluded	API-token-only; cannot inherit outer session transaction
extension_context	GET	/api/extension/context	Excluded	API-token-only; cannot inherit outer session transaction
extension_ping	GET	/api/recipes/ping	Excluded	API-token-only; cannot inherit outer session transaction
extension_recipe_defaults	GET	/api/recipes/defaults	Excluded	API-token-only; cannot inherit outer session transaction
household_browser_bridge_complete_results	POST	/api/extension/household-list/browser-bridge/complete-results	Excluded	API-token-only; cannot inherit outer session transaction
household_browser_bridge_context	GET	/api/extension/household-list/browser-bridge/context	Excluded	API-token-only; cannot inherit outer session transaction
household_browser_bridge_import	POST	/api/extension/household-list/browser-bridge/import	Excluded	API-token-only; cannot inherit outer session transaction

Connections

Endpoint ID	Method	Path	Multi API	Assessment
connections_add	POST	/admin/connections	Eligible	Verified database-backed mutation
connections_check	POST	/admin/connections/{connection_id}/check	Excluded	Mutation has non-database side effects or is not verified rollback-safe
connections_set_enabled	POST	/admin/connections/{connection_id}/enabled	Eligible	Verified database-backed mutation
connections_update	POST	/admin/connections/{connection_id}/edit	Eligible	Verified database-backed mutation

Current User

Endpoint ID	Method	Path	Multi API	Assessment
api_tester_context	GET	/api-tester/context	Eligible	Safe read operation

Data Purge

Endpoint ID	Method	Path	Multi API	Assessment
data_purge_preview	POST	/admin/purge/preview	Eligible	Safe read operation
data_purge_run_scheduled_now	POST	/admin/purge/scheduled/run	Excluded	Mutation has non-database side effects or is not verified rollback-safe
data_purge_run_selected	POST	/admin/purge/run	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Database Admin

Endpoint ID	Method	Path	Multi API	Assessment
database_apply_canonical_cleanup	POST	/admin/database/resources/{resource_key}/canonical/cleanup	Excluded	Disabled or documented-only in API Tester
database_apply_canonical_cleanup_legacy	POST	/admin/database/ingredients/canonical/cleanup	Excluded	Disabled or documented-only in API Tester
database_apply_department_review	POST	/admin/database/resources/canonical_ingredient_department_map/department-review/apply	Excluded	Disabled or documented-only in API Tester
database_canonical_bulk_update	POST	/admin/database/resources/{resource_key}/canonical/bulk-update	Excluded	Disabled or documented-only in API Tester
database_data_problems	GET	/admin/database/api/data-problems	Excluded	Disabled or documented-only in API Tester
database_data_problems_tab	GET	/admin/database/api/tabs/data-problems	Eligible	Safe read operation
database_maintenance_action	POST	/admin/database/maintenance/{action_key}	Excluded	Disabled or documented-only in API Tester
database_maintenance_action_fragment	POST	/admin/database/api/tabs/maintenance/{action_key}	Excluded	Disabled or documented-only in API Tester
database_maintenance_tab_fragment	GET	/admin/database/api/tabs/maintenance	Eligible	Safe read operation
database_merge_canonical_ingredients	POST	/admin/database/ingredients/canonical/merge	Excluded	Disabled or documented-only in API Tester
database_recipe_remove_sharing_info	POST	/admin/database/resources/recipes/rows/{row_id}/remove-sharing-info	Excluded	Disabled or documented-only in API Tester
database_recipe_restore_row	POST	/admin/database/resources/recipes/rows/{row_id}/restore	Eligible	Verified database-backed mutation
database_resource_columns_reset	POST	/admin/database/resources/{resource_key}/columns/reset	Excluded	Disabled or documented-only in API Tester
database_resource_columns_save	POST	/admin/database/resources/{resource_key}/columns	Excluded	Disabled or documented-only in API Tester
database_resource_counts	GET	/admin/database/api/resource-counts	Eligible	Safe read operation
database_resource_export_csv	GET	/admin/database/resources/{resource_key}/export.csv	Excluded	Disabled or documented-only in API Tester
database_resource_fragment	GET	/admin/database/api/resources/{resource_key}	Eligible	Safe read operation
database_resource_update_row	POST	/admin/database/resources/{resource_key}/rows/{row_id}/edit	Excluded	Disabled or documented-only in API Tester
database_resources_tab_fragment	GET	/admin/database/api/tabs/resources	Eligible	Safe read operation
database_saved_query_delete	POST	/admin/database/saved-queries/{query_id}/delete	Excluded	Disabled or documented-only in API Tester
database_saved_query_run	POST	/admin/database/saved-queries/{query_id}/run	Excluded	Disabled or documented-only in API Tester
database_saved_query_save	POST	/admin/database/saved-queries	Excluded	Disabled or documented-only in API Tester
database_sql_console_fragment	POST	/admin/database/api/tabs/sql	Excluded	Disabled or documented-only in API Tester
database_sql_console_fragment_get	GET	/admin/database/api/tabs/sql	Eligible	Safe read operation
database_sql_console_post	POST	/admin/database/sql	Excluded	Disabled or documented-only in API Tester
database_sql_console_schema	GET	/admin/database/api/sql-console/schema	Eligible	Safe read operation
database_sql_console_schema_export	GET	/admin/database/sql/schema-export	Excluded	Disabled or documented-only in API Tester
database_sql_console_table_samples	GET	/admin/database/api/sql-console/schema/{table_name}/samples	Eligible	Safe read operation
database_sql_export_csv	POST	/admin/database/sql/export.csv	Excluded	Disabled or documented-only in API Tester

Display Actions

Endpoint ID	Method	Path	Multi API	Assessment
display_render_recipe_multiplier	POST	/render-recipe-multiplier	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_restore_last_menu_image	POST	/restore-last-menu-image	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_return_to_default	POST	/return-to-default	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_run_refresh	POST	/run-refresh/{mode}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_run_reset	POST	/run-display-reset	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_set_mode	POST	/set-display-mode	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Display Administration

Endpoint ID	Method	Path	Multi API	Assessment
attached_local_eink_client_link	POST	/admin/displays/{display_id}/client-link	Excluded	Disabled or documented-only in API Tester
attached_local_eink_client_unlink	POST	/admin/displays/{display_id}/client-unlink	Excluded	Disabled or documented-only in API Tester
display_admin_add_display	POST	/admin/displays	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_advanced_settings	POST	/admin/displays/{display_id}/advanced-settings	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_bulk_set_content	POST	/admin/displays/bulk-content	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_receiver_settings	POST	/admin/displays/{display_id}/receiver-settings	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_render_settings	POST	/admin/displays/{display_id}/render-settings	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_rotate_receiver_token	POST	/admin/displays/{display_id}/receiver-token/rotate	Excluded	Disabled or documented-only in API Tester
display_admin_set_content	POST	/admin/displays/{display_id}/content	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_set_default	POST	/admin/displays/{display_id}/default	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_admin_test_preview	POST	/admin/displays/{display_id}/test-preview	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_client_generate_pairing_token	POST	/admin/display-clients/{client_id}/pairing-token	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_client_revoke_token	POST	/admin/display-clients/{client_id}/revoke-token	Excluded	Disabled or documented-only in API Tester
display_client_rotate_token	POST	/admin/display-clients/{client_id}/rotate-token	Excluded	Disabled or documented-only in API Tester
display_client_simulate_heartbeat	POST	/admin/display-clients/{client_id}/simulate-heartbeat	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Displays

Endpoint ID	Method	Path	Multi API	Assessment
assign_display_content	POST	/api/displays/assign-content	Excluded	Mutation has non-database side effects or is not verified rollback-safe
bulk_set_display_content	POST	/api/displays/bulk-content	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_assign_options	GET	/api/displays/assign-options	Eligible	Safe read operation
display_cancel_scheduled_assignment	POST	/api/displays/{display_id}/scheduled/{assignment_id}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_cancel_scheduled_assignment_delete	DELETE	/api/displays/{display_id}/scheduled/{assignment_id}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
display_delete_documented	POST	/admin/displays/{display_id}/delete	Excluded	Disabled or documented-only in API Tester
display_state	GET	/api/displays/{display_id}/state	Eligible	Safe read operation
return_displays_to_default	POST	/api/displays/return-default	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Emoji

Endpoint ID	Method	Path	Multi API	Assessment
emoji_aliases	GET	/emoji-cache/aliases	Eligible	Safe read operation
emoji_aliases_update	POST	/emoji-cache/aliases	Excluded	Mutation has non-database side effects or is not verified rollback-safe
emoji_cache_delete_legacy	POST	/emoji-cache/delete	Excluded	Disabled or documented-only in API Tester
emoji_cache_layout_legacy	POST	/emoji-cache/layout	Excluded	Mutation has non-database side effects or is not verified rollback-safe
emoji_cache_rebuild	POST	/emoji-cache/rebuild	Excluded	Mutation has non-database side effects or is not verified rollback-safe
emoji_cache_status	GET	/emoji-cache/status	Eligible	Safe read operation
emoji_group_add	POST	/emoji-cache/group	Excluded	Mutation has non-database side effects or is not verified rollback-safe
emoji_registry	GET	/emoji-cache/registry	Eligible	Safe read operation
emoji_registry_add	POST	/emoji-cache/add	Excluded	Mutation has non-database side effects or is not verified rollback-safe
emoji_supported	GET	/api/emojis/supported	Eligible	Safe read operation
emoji_validate	POST	/api/emojis/validate	Eligible	Safe read operation

Job Status Actions

Endpoint ID	Method	Path	Multi API	Assessment
job_status_bulk_action	POST	/admin/job-status/jobs/bulk	Excluded	Mutation has non-database side effects or is not verified rollback-safe
job_status_ignore	POST	/admin/job-status/jobs/{job_id}/ignore	Excluded	Mutation has non-database side effects or is not verified rollback-safe
job_status_mark_failed	POST	/admin/job-status/jobs/{job_id}/mark-failed	Excluded	Mutation has non-database side effects or is not verified rollback-safe
job_status_mark_failed_ignore	POST	/admin/job-status/jobs/{job_id}/mark-failed-ignore	Excluded	Mutation has non-database side effects or is not verified rollback-safe
job_status_retry	POST	/admin/job-status/jobs/{job_id}/retry	Excluded	Mutation has non-database side effects or is not verified rollback-safe
job_status_review	POST	/admin/job-status/jobs/{job_id}/review	Excluded	Mutation has non-database side effects or is not verified rollback-safe
legacy_background_operations_bulk_action	POST	/admin/background-operations/jobs/bulk	Excluded	Mutation has non-database side effects or is not verified rollback-safe
legacy_background_operations_ignore_job	POST	/admin/background-operations/jobs/{job_id}/ignore	Excluded	Mutation has non-database side effects or is not verified rollback-safe
legacy_background_operations_mark_failed	POST	/admin/background-operations/jobs/{job_id}/mark-failed	Excluded	Mutation has non-database side effects or is not verified rollback-safe
legacy_background_operations_mark_failed_ignore	POST	/admin/background-operations/jobs/{job_id}/mark-failed-ignore	Excluded	Mutation has non-database side effects or is not verified rollback-safe
legacy_background_operations_retry_job	POST	/admin/background-operations/jobs/{job_id}/retry	Excluded	Mutation has non-database side effects or is not verified rollback-safe
legacy_background_operations_review_job	POST	/admin/background-operations/jobs/{job_id}/review	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Jobs

Endpoint ID	Method	Path	Multi API	Assessment
shopping_list_status_jobs	GET	/status/jobs	Eligible	Safe read operation

Kiosk Display

Endpoint ID	Method	Path	Multi API	Assessment
kiosk_display_page	GET	/kiosk/{display_id}	Eligible	Safe read operation
kiosk_ingredient_index	GET	/api/kiosk/{display_id}/ingredient-index	Eligible	Safe read operation
kiosk_lets_cook_end	POST	/api/kiosk/{display_id}/lets-cook/session/{session_id}/end	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_lets_cook_ingredient_toggle	POST	/api/kiosk/{display_id}/lets-cook/session/{session_id}/ingredients/{ingredient_key}/toggle	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_lets_cook_start	POST	/api/kiosk/{display_id}/lets-cook	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_lets_cook_state	GET	/api/kiosk/{display_id}/lets-cook/state	Eligible	Safe read operation
kiosk_lets_cook_step_toggle	POST	/api/kiosk/{display_id}/lets-cook/session/{session_id}/steps/{step_key}/toggle	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_lets_cook_timer_action	POST	/api/kiosk/{display_id}/lets-cook/session/{session_id}/timers/{timer_id}/{action}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_lets_cook_timer_start	POST	/api/kiosk/{display_id}/lets-cook/session/{session_id}/timers	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_meal_plan	GET	/api/kiosk/{display_id}/meal-plan	Eligible	Safe read operation
kiosk_recipe_thumbnail	GET	/api/kiosk/{display_id}/recipe-thumbnail/{recipe_id}	Eligible	Safe read operation
kiosk_recipes	GET	/api/kiosk/{display_id}/recipes	Eligible	Safe read operation
kiosk_return_default	POST	/api/kiosk/{display_id}/return-default	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_show_meal_plan	POST	/api/kiosk/{display_id}/show-meal-plan	Excluded	Mutation has non-database side effects or is not verified rollback-safe
kiosk_show_recipe	POST	/api/kiosk/{display_id}/show-recipe	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Kitchen Inventory

Endpoint ID	Method	Path	Multi API	Assessment
inventory_admin_add_item	POST	/admin/kitchen-inventory/add	Eligible	Verified database-backed mutation
inventory_admin_mark_not_on_hand	POST	/admin/kitchen-inventory/{inventory_item_id}/not-on-hand	Eligible	Verified database-backed mutation
inventory_admin_mark_on_hand	POST	/admin/kitchen-inventory/{inventory_item_id}/on-hand	Eligible	Verified database-backed mutation
inventory_admin_move_location	POST	/admin/kitchen-inventory/{inventory_item_id}/location	Eligible	Verified database-backed mutation
inventory_admin_update_item	POST	/admin/kitchen-inventory/{inventory_item_id}/update	Eligible	Verified database-backed mutation
inventory_location_add	POST	/admin/kitchen-inventory/location/add	Eligible	Verified database-backed mutation
inventory_location_delete	POST	/admin/kitchen-inventory/location/{location_id}/delete	Excluded	Disabled or documented-only in API Tester
inventory_location_update	POST	/admin/kitchen-inventory/location/{location_id}/update	Eligible	Verified database-backed mutation
inventory_locations_reorder	POST	/admin/kitchen-inventory/locations/reorder	Eligible	Verified database-backed mutation
mobile_inventory_add_item	POST	/mobile/kitchen-inventory/add	Eligible	Verified database-backed mutation
mobile_inventory_mark_not_on_hand	POST	/mobile/kitchen-inventory/{inventory_item_id}/not-on-hand	Eligible	Verified database-backed mutation
mobile_inventory_mark_on_hand	POST	/mobile/kitchen-inventory/{inventory_item_id}/on-hand	Eligible	Verified database-backed mutation
mobile_inventory_update_item	POST	/mobile/kitchen-inventory/{inventory_item_id}/update	Eligible	Verified database-backed mutation

Let’s Cook

Endpoint ID	Method	Path	Multi API	Assessment
lets_cook_context	GET	/api/lets-cook/context	Eligible	Safe read operation
lets_cook_end	POST	/api/lets-cook/sessions/{session_id}/end	Excluded	Mutation has non-database side effects or is not verified rollback-safe
lets_cook_history	GET	/api/lets-cook/history	Eligible	Safe read operation
lets_cook_history_detail	GET	/api/lets-cook/history/{session_id}	Eligible	Safe read operation
lets_cook_ingredient_toggle	POST	/api/lets-cook/sessions/{session_id}/ingredients/{ingredient_key}/toggle	Excluded	Mutation has non-database side effects or is not verified rollback-safe
lets_cook_session	GET	/api/lets-cook/sessions/{session_id}	Eligible	Safe read operation
lets_cook_show_entire_recipe	POST	/api/lets-cook/sessions/{session_id}/show-entire-recipe	Excluded	Mutation has non-database side effects or is not verified rollback-safe
lets_cook_start	POST	/api/lets-cook/sessions	Excluded	Mutation has non-database side effects or is not verified rollback-safe
lets_cook_step_toggle	POST	/api/lets-cook/sessions/{session_id}/steps/{step_key}/toggle	Excluded	Mutation has non-database side effects or is not verified rollback-safe
lets_cook_timer_action	POST	/api/lets-cook/sessions/{session_id}/timers/{timer_id}/{action}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
lets_cook_timer_start	POST	/api/lets-cook/sessions/{session_id}/timers	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Meal Planner

Endpoint ID	Method	Path	Multi API	Assessment
meal_planner_create_entry	POST	/admin/meal-planner/entries	Eligible	Verified database-backed mutation
meal_planner_create_shopping_list	POST	/admin/meal-planner/create-shopping-list	Eligible	Verified database-backed mutation
meal_planner_create_slot	POST	/admin/meal-planner/slots	Eligible	Verified database-backed mutation
meal_planner_day	GET	/admin/meal-planner/day/{plan_date}	Eligible	Safe read operation
meal_planner_delete_entry_api	DELETE	/admin/meal-planner/entries/{entry_id}	Excluded	Destructive endpoint
meal_planner_events	GET	/admin/meal-planner/events	Eligible	Safe read operation
meal_planner_home_future_entry	POST	/api/meal-planner/home-future-entry	Eligible	Verified database-backed mutation
meal_planner_move_day	POST	/admin/meal-planner/days/move	Eligible	Verified database-backed mutation
meal_planner_move_entry	POST	/admin/meal-planner/entries/{entry_id}/move	Eligible	Verified database-backed mutation
meal_planner_move_slot	POST	/admin/meal-planner/slots/move	Eligible	Verified database-backed mutation
meal_planner_preview_shopping_list	POST	/admin/meal-planner/preview-shopping-list	Eligible	Safe read operation
meal_planner_recipe_add_options	GET	/api/meal-planner/recipe-add-options/{recipe_id}	Eligible	Safe read operation
meal_planner_recipe_search	GET	/admin/meal-planner/recipe-search	Eligible	Safe read operation
meal_planner_reorder_slots	POST	/admin/meal-planner/slots/reorder	Eligible	Verified database-backed mutation
meal_planner_review	GET	/admin/meal-planner/review	Eligible	Safe read operation
meal_planner_review_email	POST	/admin/meal-planner/review/email	Excluded	Mutation has non-database side effects or is not verified rollback-safe
meal_planner_settings	GET	/admin/meal-planner/settings	Eligible	Safe read operation
meal_planner_settings_patch	PATCH	/admin/meal-planner/settings	Eligible	Verified database-backed mutation
meal_planner_update_entry	POST	/admin/meal-planner/entries/{entry_id}	Eligible	Verified database-backed mutation
meal_planner_update_entry_patch	PATCH	/admin/meal-planner/entries/{entry_id}	Eligible	Verified database-backed mutation
meal_planner_update_settings	POST	/admin/meal-planner/settings	Eligible	Verified database-backed mutation
meal_planner_update_slot	POST	/admin/meal-planner/slots/{slot_id}	Eligible	Verified database-backed mutation
meal_planner_update_slot_patch	PATCH	/admin/meal-planner/slots/{slot_id}	Eligible	Verified database-backed mutation

Mobile UI Actions

Endpoint ID	Method	Path	Multi API	Assessment
mobile_add_recipe_submit	POST	/mobile/add-recipe	Excluded	Mutation has non-database side effects or is not verified rollback-safe
mobile_extract_url_photo	POST	/mobile/extract-url	Excluded	Disabled or documented-only in API Tester
mobile_made_it_photo_upload	POST	/mobile/made-it-photo/{recipe_id}	Excluded	Disabled or documented-only in API Tester
mobile_normal_mode	POST	/mobile/normal-mode	Excluded	Mutation has non-database side effects or is not verified rollback-safe
mobile_render_recipe	POST	/mobile/render-recipe	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_pdf_file	GET	/recipe-pdf/{recipe_id}	Excluded	Disabled or documented-only in API Tester

Organization Management

Endpoint ID	Method	Path	Multi API	Assessment
organization_archive	POST	/admin/organizations/{organization_id}/archive	Excluded	Disabled or documented-only in API Tester
organization_backup	POST	/admin/organizations/{organization_id}/backup	Excluded	Mutation has non-database side effects or is not verified rollback-safe
organization_bulk_action	POST	/admin/organizations/bulk-action	Excluded	Disabled or documented-only in API Tester
organization_config_pull_current	POST	/admin/organization/config-pull/{domain_key}	Eligible	Verified database-backed mutation
organization_config_push_all	POST	/admin/organizations/config-push	Excluded	Disabled or documented-only in API Tester
organization_config_push_domain_all	POST	/admin/organizations/config-push/{domain_key}	Excluded	Disabled or documented-only in API Tester
organization_config_push_domain_one	POST	/admin/organizations/{organization_id}/config-push/{domain_key}	Eligible	Verified database-backed mutation
organization_create	POST	/admin/organizations	Excluded	Mutation has non-database side effects or is not verified rollback-safe
organization_delete	POST	/admin/organizations/{organization_id}/delete	Excluded	Disabled or documented-only in API Tester
organization_disable	POST	/admin/organizations/{organization_id}/disable	Excluded	Disabled or documented-only in API Tester
organization_disable_membership	POST	/admin/organizations/{organization_id}/users/{user_id}/disable	Excluded	Disabled or documented-only in API Tester
organization_enable	POST	/admin/organizations/{organization_id}/enable	Excluded	Disabled or documented-only in API Tester
organization_enable_membership	POST	/admin/organizations/{organization_id}/users/{user_id}/enable	Excluded	Disabled or documented-only in API Tester
organization_invite_resend	POST	/admin/organizations/{organization_id}/invites/{invite_id}/resend	Excluded	Mutation has non-database side effects or is not verified rollback-safe
organization_invite_revoke	POST	/admin/organizations/{organization_id}/invites/{invite_id}/revoke	Excluded	Disabled or documented-only in API Tester
organization_queue_current_recipe_cache	POST	/admin/organization/recipe-cache/queue	Excluded	Mutation has non-database side effects or is not verified rollback-safe
organization_queue_recipe_cache_by_id	POST	/admin/organizations/{organization_id}/recipe-cache/queue	Excluded	Mutation has non-database side effects or is not verified rollback-safe
organization_restore	POST	/admin/organizations/{organization_id}/restore	Excluded	Disabled or documented-only in API Tester
organization_revoke_ownership_transfer	POST	/admin/organizations/{organization_id}/ownership/transfers/{transfer_public_id}/revoke	Excluded	Disabled or documented-only in API Tester
organization_stripe_status	POST	/admin/organizations/{organization_id}/stripe-status	Excluded	Disabled or documented-only in API Tester
organization_switch_legacy_route	POST	/admin/organizations/switch	Excluded	Self/context-changing endpoint
organization_sync_login_providers	POST	/admin/organizations/{organization_id}/sync-login-providers	Eligible	Verified database-backed mutation
organization_transfer_ownership	POST	/admin/organizations/{organization_id}/ownership/transfer	Excluded	Disabled or documented-only in API Tester
organization_transfer_ownership_invite	POST	/admin/organizations/{organization_id}/ownership/transfer-invite	Excluded	Disabled or documented-only in API Tester
organization_update_by_id	POST	/admin/organizations/{organization_id}/update	Eligible	Verified database-backed mutation
organization_update_current	POST	/admin/organization/update	Eligible	Verified database-backed mutation
organization_update_mfa	POST	/admin/organizations/{organization_id}/mfa	Eligible	Verified database-backed mutation
system_organization_purge_dry_run	POST	/admin/system/purge/organizations/{organization_id}/dry-run	Eligible	Safe read operation
system_recovery_invite_primary_admin	POST	/admin/system/organizations/{organization_id}/invite-primary-admin	Excluded	Disabled or documented-only in API Tester

Performance

Endpoint ID	Method	Path	Multi API	Assessment
performance_resource_snapshot	GET	/admin/performance/resource-snapshot	Eligible	Safe read operation

Recipe Discovery

Endpoint ID	Method	Path	Multi API	Assessment
recipe_discovery_inventory	GET	/recipes/discovery/inventory-ingredients	Eligible	Safe read operation
recipe_discovery_preview	POST	/recipes/discovery/preview	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_discovery_preview_status	GET	/recipes/discovery/preview-status/{job_id}	Eligible	Safe read operation
recipe_discovery_preview_url	POST	/recipes/discovery/preview-url	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_discovery_save	POST	/recipes/discovery/save	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_discovery_search	POST	/recipes/discovery/search	Eligible	Safe read operation

Recipe Library

Endpoint ID	Method	Path	Multi API	Assessment
recipe_library_add_recipe	POST	/add-recipe	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_library_archive_recipe	POST	/delete-recipe/{recipe_id}	Excluded	Disabled or documented-only in API Tester
recipe_library_bulk_recipe_type	POST	/api/recipes/bulk-recipe-type	Eligible	Verified database-backed mutation
recipe_library_manual_recipe	POST	/manual-recipe	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_library_prepare_editable_content	POST	/prepare-edit-recipe-content/{recipe_id}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_library_save_editable_content	POST	/save-edit-recipe-content/{recipe_id}	Eligible	Verified database-backed mutation
recipe_library_select_recipe	POST	/select-recipe	Eligible	Verified database-backed mutation

Recipe Sharing

Endpoint ID	Method	Path	Multi API	Assessment
recipe_share_create_link	POST	/api/recipe-shares/link	Eligible	Verified database-backed mutation
recipe_share_create_link_for_recipe	POST	/api/recipe-shares/{recipe_id}/link	Eligible	Verified database-backed mutation
recipe_share_email_invite	POST	/api/recipe-shares/{public_id}/email-invite	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_share_email_pdfs	POST	/api/recipe-shares/email-pdfs	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_share_export_file	POST	/api/recipe-shares/export/file	Eligible	Safe read operation
recipe_share_external_manifest	POST	/api/recipe-shares/external/manifest	Eligible	Safe read operation
recipe_share_external_payload	POST	/api/recipe-shares/external/payload	Eligible	Safe read operation
recipe_share_import	POST	/api/recipe-shares/import	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_share_import_external	POST	/api/recipe-shares/import/external	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_share_import_external_manifest	POST	/api/recipe-shares/import/external/manifest	Eligible	Safe read operation
recipe_share_import_file	POST	/api/recipe-shares/import/file	Excluded	Disabled or documented-only in API Tester
recipe_share_import_file_preview	POST	/api/recipe-shares/import/file/preview	Excluded	Disabled or documented-only in API Tester
recipe_share_import_manifest	POST	/api/recipe-shares/import/manifest	Eligible	Safe read operation
recipe_share_legacy_create	POST	/share-recipe/{recipe_id}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_share_notification_dismiss	POST	/api/recipe-share-notifications/{notification_id}/dismiss	Eligible	Verified database-backed mutation
recipe_share_recipient_target_summary	POST	/api/recipe-shares/recipient-target-summary	Eligible	Safe read operation
recipe_share_revoke	POST	/api/recipe-shares/{public_id}/revoke	Eligible	Verified database-backed mutation
recipe_share_target_dismiss	POST	/api/recipe-share-targets/{target_id}/dismiss	Eligible	Verified database-backed mutation
recipe_shares_active_outbound	GET	/api/recipe-shares/outbound/active	Eligible	Safe read operation
recipe_shares_shared_with_me	GET	/api/recipe-shares/shared-with-me	Eligible	Safe read operation

Recipes

Endpoint ID	Method	Path	Multi API	Assessment
ingredient_index	GET	/ingredient-index	Eligible	Safe read operation
queue_recipe_cache_rebuild	POST	/refresh-recipe/{recipe_id}	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_cache_status	GET	/api/recipes/{recipe_id}/cache-status	Eligible	Safe read operation
recipe_cache_statuses	GET	/api/recipes/cache-statuses	Eligible	Safe read operation
recipe_dependencies	GET	/recipe-dependencies/{recipe_id}	Eligible	Safe read operation
recipe_details	GET	/get-recipe/{recipe_id}	Eligible	Safe read operation
recipe_search	GET	/recipes	Eligible	Safe read operation

Regression Tests

Endpoint ID	Method	Path	Multi API	Assessment
regression_performance_fragment	GET	/admin/regression-tests/api/performance	Eligible	Safe read operation

Remote Display Client

Endpoint ID	Method	Path	Multi API	Assessment
remote_display_client_heartbeat	POST	/api/display-client/heartbeat	Excluded	Mutation has non-database side effects or is not verified rollback-safe
remote_display_client_pair	POST	/api/display-client/pair	Excluded	Mutation has non-database side effects or is not verified rollback-safe
remote_display_client_panel_transport	GET	/api/display-client/panel-transport	Eligible	Safe read operation
remote_display_client_preview	GET	/api/display-client/preview	Excluded	Disabled or documented-only in API Tester
remote_display_client_state	GET	/api/display-client/state	Eligible	Safe read operation
remote_display_client_unlink	POST	/api/display-client/unlink	Excluded	Destructive endpoint

Settings

Endpoint ID	Method	Path	Multi API	Assessment
settings_access_activity_update_assets	POST	/admin/config/platform/access-activity/update-assets	Excluded	Mutation has non-database side effects or is not verified rollback-safe
settings_add_translation_rule	POST	/add-translation	Eligible	Verified database-backed mutation
settings_config_push_login_providers	POST	/admin/platform/config-push/login-providers	Excluded	Disabled or documented-only in API Tester
settings_country_flags_update_assets	POST	/admin/config/platform/country-flags/update-assets	Excluded	Mutation has non-database side effects or is not verified rollback-safe
settings_delete_translation_rule	POST	/delete-translation	Excluded	Disabled or documented-only in API Tester
settings_export_config	GET	/admin/system/export-config	Excluded	Disabled or documented-only in API Tester
settings_geoip_lookup	GET	/admin/config/platform/geoip/lookup	Eligible	Safe read operation
settings_geoip_update	POST	/admin/config/platform/geoip/update	Eligible	Verified database-backed mutation
settings_noun_project_connection_test	POST	/api/noun-project/test	Excluded	Mutation has non-database side effects or is not verified rollback-safe
settings_organization_login_provider_save	POST	/admin/organization/login-providers/{provider_key}/save	Eligible	Verified database-backed mutation
settings_organization_mfa_policy_save	POST	/admin/organization/security/mfa-policy	Eligible	Verified database-backed mutation
settings_platform_auth_provider_configure	POST	/admin/platform/auth-providers/{provider_key}/configure	Eligible	Verified database-backed mutation
settings_recipe_discovery_restore_defaults	POST	/admin/config/platform/recipe_discovery/restore-defaults	Eligible	Verified database-backed mutation
settings_save_legacy	POST	/save-settings	Excluded	Disabled or documented-only in API Tester
settings_save_scoped_config	POST	/admin/config/{scope_type}/{key_prefix}/save	Eligible	Verified database-backed mutation
settings_save_translation_rules	POST	/save-translations	Eligible	Verified database-backed mutation
settings_scoped_config_page	GET	/admin/config/{scope_type}/{key_prefix}	Excluded	Disabled or documented-only in API Tester
settings_shop_with_provider_save	POST	/admin/config/platform/shop-with-providers	Eligible	Verified database-backed mutation
shop_with_provider_config_save_legacy	POST	/admin/shop-with-providers	Eligible	Verified database-backed mutation

Shopping Lists

Endpoint ID	Method	Path	Multi API	Assessment
admin_assisted_browser_control	POST	/admin/shop-a-list/{list_id}/assisted/browser/control	Excluded	Mutation has non-database side effects or is not verified rollback-safe
admin_assisted_browser_navigate	POST	/admin/shop-a-list/{list_id}/assisted/browser/navigate	Excluded	Mutation has non-database side effects or is not verified rollback-safe
admin_assisted_browser_screenshot	GET	/admin/shop-a-list/{list_id}/assisted/browser/screenshot/{session_id}.png	Excluded	Disabled or documented-only in API Tester
admin_assisted_browser_start	POST	/admin/shop-a-list/{list_id}/assisted/browser/start	Excluded	Mutation has non-database side effects or is not verified rollback-safe
admin_assisted_browser_stop	POST	/admin/shop-a-list/{list_id}/assisted/browser/stop	Excluded	Mutation has non-database side effects or is not verified rollback-safe
recipe_cart	GET	/recipe-cart	Eligible	Safe read operation
recipe_cart_add	POST	/recipe-cart/add	Eligible	Verified database-backed mutation
recipe_cart_clear	POST	/recipe-cart/clear	Eligible	Verified database-backed mutation
recipe_cart_create_shopping_list	POST	/recipe-cart/create-shopping-list	Eligible	Verified database-backed mutation
recipe_cart_remove	POST	/recipe-cart/remove	Eligible	Verified database-backed mutation
recipe_cart_update	POST	/recipe-cart/update	Eligible	Verified database-backed mutation
shopping_department_add	POST	/admin/shop-a-list/departments/add	Eligible	Verified database-backed mutation
shopping_department_delete	POST	/admin/shop-a-list/departments/{department_id}/delete	Excluded	Disabled or documented-only in API Tester
shopping_department_reorder	POST	/admin/shop-a-list/departments/reorder	Eligible	Verified database-backed mutation
shopping_department_update	POST	/admin/shop-a-list/departments/{department_id}/update	Eligible	Verified database-backed mutation
shopping_household_settings_save	POST	/admin/household-list	Eligible	Verified database-backed mutation
shopping_list_add_manual_item	POST	/shopping-list/{list_id}/manual-item	Eligible	Verified database-backed mutation
shopping_list_already_have_form	POST	/shopping-list/{list_id}/already-have	Eligible	Verified database-backed mutation
shopping_list_complete	POST	/shopping-list/{list_id}/complete	Eligible	Verified database-backed mutation
shopping_list_delete_form	POST	/shopping-list/{list_id}/delete	Excluded	Disabled or documented-only in API Tester
shopping_list_external_completion_tasks	POST	/shopping-list/{list_id}/external-items/complete-tasks	Eligible	Safe read operation
shopping_list_item_department	POST	/shopping-list/{list_id}/item-department	Eligible	Verified database-backed mutation
shopping_list_manual_item_anchor	POST	/shopping-list/{list_id}/manual-item/anchor	Eligible	Verified database-backed mutation
shopping_list_manual_item_delete	POST	/shopping-list/{list_id}/manual-item/delete	Eligible	Verified database-backed mutation
shopping_list_manual_item_ignore	POST	/shopping-list/{list_id}/manual-item/ignore	Eligible	Verified database-backed mutation
shopping_list_manual_item_undo_delete	POST	/shopping-list/{list_id}/manual-item/undo-delete	Eligible	Verified database-backed mutation
shopping_list_new	POST	/shopping-list/new	Eligible	Verified database-backed mutation
shopping_list_open_in_recipes	POST	/shopping-list/{list_id}/open-in-recipes	Eligible	Verified database-backed mutation
shopping_list_rebuild_form	POST	/shopping-list/{list_id}/rebuild	Eligible	Verified database-backed mutation
shopping_list_reopen_form	POST	/shopping-list/{list_id}/reopen	Eligible	Verified database-backed mutation
shopping_list_save_form	POST	/shopping-list/{list_id}/save	Eligible	Verified database-backed mutation
shopping_list_set_active_form	POST	/shopping-list/{list_id}/set-active	Eligible	Verified database-backed mutation
shopping_list_toggle_item	POST	/shopping-list/{list_id}/toggle	Eligible	Verified database-backed mutation

Status / Runtime

Endpoint ID	Method	Path	Multi API	Assessment
status_backup	GET	/status/backup	Eligible	Safe read operation
status_display	GET	/status/display	Eligible	Safe read operation
status_overview	GET	/status	Eligible	Safe read operation
status_recipe_cache	GET	/status/recipe-cache	Eligible	Safe read operation
status_render	GET	/status/render	Eligible	Safe read operation
system	GET	/about	Eligible	Safe read operation

Support Requests

Endpoint ID	Method	Path	Multi API	Assessment
support_request_status	GET	/admin/support/status	Eligible	Safe read operation
support_request_submit	POST	/admin/support/request	Excluded	Mutation has non-database side effects or is not verified rollback-safe

System

Endpoint ID	Method	Path	Multi API	Assessment
noun_project_connection_test	POST	/api/noun-project/test	Eligible	Safe read operation
system_audit_job_status	GET	/admin/system/audit-job-status	Eligible	Safe read operation
system_database_parity_audit_start	POST	/admin/system/database-parity-audit	Excluded	Mutation has non-database side effects or is not verified rollback-safe
system_database_parity_repair_start	POST	/admin/system/database-parity-repair	Excluded	Disabled or documented-only in API Tester
system_direct_sql_audit_start	POST	/admin/system/direct-sql-audit	Excluded	Mutation has non-database side effects or is not verified rollback-safe
system_instance_reporting_trigger	POST	/api/system/instance-reporting/trigger	Excluded	Mutation has non-database side effects or is not verified rollback-safe

User Management

Endpoint ID	Method	Path	Multi API	Assessment
audit_prune	POST	/admin/audit/prune	Excluded	Disabled or documented-only in API Tester
auth_user_mfa_reset	POST	/admin/users/{user_id}/mfa/reset	Excluded	Disabled or documented-only in API Tester
auth_user_trusted_browsers_clear	POST	/admin/users/{user_id}/mfa/trusted-browsers/clear	Excluded	Disabled or documented-only in API Tester
security_settings_save	POST	/admin/security	Eligible	Verified database-backed mutation
user_bulk_action	POST	/admin/users/bulk-action	Excluded	Disabled or documented-only in API Tester
user_create_api_token	POST	/admin/users/{user_id}/tokens/create	Excluded	Disabled or documented-only in API Tester
user_invite	POST	/admin/users/invite	Excluded	Mutation has non-database side effects or is not verified rollback-safe
user_invite_resend	POST	/admin/invites/{invite_id}/resend	Excluded	Mutation has non-database side effects or is not verified rollback-safe
user_invite_revoke	POST	/admin/invites/{invite_id}/revoke	Excluded	Disabled or documented-only in API Tester
user_reset_password	POST	/admin/users/{user_id}/reset-password	Excluded	Mutation has non-database side effects or is not verified rollback-safe
user_revoke_api_token	POST	/admin/tokens/{token_id}/revoke	Excluded	Disabled or documented-only in API Tester
user_update	POST	/admin/users/{user_id}/update	Eligible	Verified database-backed mutation

Voice Assistant Test

Endpoint ID	Method	Path	Multi API	Assessment
voice_alexa_status	GET	/api/voice/alexa/status	Eligible	Safe read operation
voice_google_home_status	GET	/api/voice/google-home/status	Eligible	Safe read operation
voice_test_command	POST	/api/voice/test-command	Excluded	Mutation has non-database side effects or is not verified rollback-safe

Postman execution

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 endpoints

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.

Session-authenticated endpoints

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 and balance-inspection endpoints:

• GET /api/admin/ai/usage
• 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 copied Postman token preserves the signed-in user's permissions and organization context. Provider request IDs and provider-reported token counts remain System Admin-only. The collection intentionally omits AI Seed adjustment writes because those operations change audited balances.

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.