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.
Canonical, compatibility, and retired APIs
Blackcap distinguishes a canonical endpoint from a compatibility alias when two URLs perform the same operation. Built-in Blackcap callers use the canonical URL. A retained compatibility route continues to execute normally rather than redirecting a mutating request, but its response advertises:
Deprecation: trueX-Blackcap-Deprecated-Endpoint: trueX-Blackcap-Successor: <canonical path>- a
Linkresponse header withrel="successor-version" - a
299 Blackcapwarning identifying the successor
No Sunset header is emitted until Blackcap intentionally schedules a removal release/date. Authentication, organization scoping, CSRF requirements, permissions, and response-body semantics remain authoritative on a retained route.
The first intentional retirement release removes 13 duplicate Flask route registrations: POST /recipes/discovery/preview-url, the path-ID Recipe Share Link route, /share-recipe/<recipe_id>, /api/displays/bulk-content, and the nine /api/displays/<display_id>/lets-cook/... duplicates. Requests to those retired URLs receive HTTP 410 Gone from a centralized retirement guard with X-Blackcap-Retired-Endpoint: true, X-Blackcap-Successor, and a successor Link; the retired handler itself is no longer registered or executed. Their canonical routes are POST /recipes/discovery/preview, POST /api/recipe-shares/link, POST /api/recipe-shares/email-pdfs, POST /api/displays/assign-content, and /api/kiosk/<display_id>/lets-cook/....
Phase 2 retires 21 additional internal Admin/action aliases after Blackcap-owned callers moved to canonical routes: six Background Operations job actions, nine /admin/system/ai/... actions/downloads, two 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 (whose canonical resource-scoped successor is POST /admin/database/resources/recipe_ingredients/canonical/cleanup). Together with Phase 1, 34 method/path aliases are retired.
Phase 3 retires GET and POST /admin/shop-with-providers in favor of /admin/config/platform/shop-with-providers, bringing the total to 36 retired method/path aliases. These user-facing compatibility routes now receive HTTP 410 with successor metadata rather than executing a redirect/form adapter.
Only two compatibility method/path aliases remain callable: the legacy Dropbox and Google OAuth callbacks. They are intentionally retained because callback URLs may be configured outside Blackcap; new provider applications and new Blackcap configuration should use the canonical /cloud-backup/... callbacks.
HTTP consolidation does not mean collapsing distinct authentication boundaries. For example, Admin and Chrome Extension Support Chat routes remain separate transports because browser-session and API-token authorization differ even though they already share Support Chat services. Similarly, distinct Assisted Shopping actions remain distinct endpoints but now share transition helpers.
Shared command/service boundaries
The reconciliation also removes duplicated business logic where URLs should remain separate:
- Recipe Write centralizes canonical recipe metadata persistence across URL Add, Extension structured capture, Mobile URL Add, Discovery Save, and the final write step reached by manual/photo/social/import adapters. Optional
cookbook_category_idsare validated in the active/receiving organization and are committed with the recipe when supplied; omission remains backward compatible. The same write/normalization path derives missing Total Time from non-overlapping canonical duration buckets while preserving an explicit Total Time. The derived value is written into the canonicaltotal_minutescolumn; read/display surfaces do not calculate it again on every request, and sparse edits preserve the stored duration metadata. - Recipe Cart → Shopping List keeps list persistence and Recipe Cart clearing in the same application transaction. A successful conversion returns the cleared cart and the created Shopping List for the Recipe Library confirmation.
POST /shopping-list/{list_id}/recipe-multiplierpersists a changed source-recipe multiplier and returns the rebuilt ingredient payload immediately, using the same multiplier constraints as Recipe Cart. - Recipe PDF email centralizes recipient validation, temporary PDF rendering, SMTP delivery, and cleanup across the canonical browser and Extension adapters; the old one-recipe browser URL is retired.
- Display assignment centralizes action/settings normalization before calling the durable display-assignment service.
- Extension recipe defaults centralizes the overlapping organization/default payload used by
pinganddefaults. - Assisted Shopping transitions centralize checked/skipped/next-item/progress behavior while preserving explicit action URLs.
Curated API and Postman route coverage
Blackcap does not expose every Flask route blindly through API Tester or Postman. The curated registry records authentication, permissions, organization scope, safe-to-run status, destructive behavior, parameter schemas, examples, and Postman eligibility. A source-level route-coverage regression check compares canonical /api/... Blueprint routes with that registry and permits only reviewed compatibility aliases.
The live /api-tester/spec response is the authoritative count of registered, runnable, Postman-eligible, and Multi API endpoints. Counts are intentionally not duplicated in this document because they change as curated endpoints are added or retired. Retired endpoints are excluded from the active registry; the few retained compatibility aliases remain visible and are labeled with deprecation/successor metadata.
The review keeps canonical API Tester/Postman coverage for AI Recipe Images, browser-session Social Recipe Imports, Recipe multiplier options, Kiosk/Let’s Cook presentation actions, and Shop With skip/clear-skips. The AI candidate-image binary route is deliberately documented-only. The nine retired /api/displays/... Let’s Cook duplicates no longer appear in generated collections; only their canonical /api/kiosk/... equivalents remain active.
See API Tester and Postman for the operator workflow and export rules.
API eligibility and orchestration
Multi API eligibility is generated from the same curated API Tester registry returned by /api-tester/spec; the live spec is authoritative. The registry now treats eligibility as an explicit transaction-safety audit rather than assuming every read_only=True operation is safe.
An operation can be offered as a Multi API sub-request only when all of the following are true:
- it can execute through the logged-in API Tester session and current organization context;
- it is enabled for API Tester execution and is not marked destructive;
- it is not an API-token-only or multipart/file-upload operation;
- a mutation has been individually verified to keep its meaningful state inside Blackcap's centralized app-database transaction; and
- a read-like operation has no hidden write, external-provider call, generated/binary file response, runtime-only mutation, or other effect that escapes the outer transaction.
The transaction is ordered and all-or-nothing. A contained route that reports an HTTP error or follows Blackcap's normal form pattern of flashing an error/danger message and redirecting is treated as a failed sub-request, and all prior database changes are rolled back. Configuration-backed mutations defer their in-memory/config-file mirror refresh until the outer transaction commits so a later failed operation cannot leave runtime configuration ahead of the database.
Verified transactional mutations
Safe reads are included dynamically after the read-side audit above. The following mutating endpoint IDs have been explicitly reviewed as transaction-safe:
| Area | Verified mutating sub-APIs |
|---|---|
| AI Recipe Images | ai_recipe_image_job_accept, ai_recipe_image_job_reject |
| Connections | connections_add, connections_set_enabled, connections_update |
| Cookbook Categories | cookbook_categories_create, cookbook_categories_update, cookbook_category_recipe_assignments, cookbook_category_recipe_update, cookbook_category_remove_all_assignments |
| Display Administration | display_admin_set_default, display_admin_receiver_settings, display_admin_render_settings, display_client_simulate_heartbeat |
| Emoji | emoji_aliases_update |
| Job Status | job_status_review, job_status_ignore, job_status_mark_failed, job_status_mark_failed_ignore |
| Kitchen Inventory | Logical-item add/update/on-hand/restore/location/reorder plus DB-only physical Package add, remaining quantity, optional freshness-date set/clear, and retained Product detail edits. Product/overview photo multipart capture, AI/provider work, file cleanup, and destructive actions remain excluded |
| Meal Planner | DB-backed entry, Meal rename, people-served, slot, move/reorder, settings, future-entry, and shopping-list creation operations; Plan Meals AI/provider/job operations, Recipe-Suggestion follow-on AI, provider/job/file operations, and durable-plan deletion remain excluded |
| Organization Management | organization_update_current, organization_update_by_id, organization_config_pull_current, organization_config_push_domain_one, organization_update_mfa, organization_sync_login_providers |
| Recipe Library | recipe_library_bulk_recipe_type |
| Recipe Sharing | recipe_share_create_link, recipe_share_revoke, recipe_share_notification_dismiss, recipe_share_target_dismiss |
| Settings | DB-backed scoped configuration, Recipe Discovery defaults, Shop With provider, translation-rule, login-provider, MFA-policy, and platform Ingredient Density and FoodKeeper Shelf Life add/save operations that participate in the centralized transaction |
| Shopping Lists | DB-backed Recipe Cart, Shopping List item/state, household settings, and department operations; browser-driving shopping operations remain excluded |
| Social Recipe Imports | social_recipe_import_keep_current, social_recipe_import_cancel; candidate creation and retry remain excluded because they can create recipes/start work |
| User Management | user_update, security_settings_save |
The platform Ingredient Density JSON API (GET/POST /api/platform/ingredient-densities and POST /api/platform/ingredient-densities/{density_id}) is the programmatic counterpart to the System Admin configuration page. Its read plus add/save operations are transaction-safe. Kitchen Inventory Product/overview image uploads and the Made It multipart update are executable in ordinary API Tester/Postman workflows but are not Multi API sub-requests because multipart/file effects are intentionally outside the transaction boundary.
The platform FoodKeeper Shelf Life JSON API mirrors Platform Configuration → FoodKeeper Shelf Life with list/add/save endpoints under /api/platform/foodkeeper-shelf-life. Those database-only operations are transaction-safe. POST /api/platform/foodkeeper-shelf-life/refresh fetches the external USDA FoodKeeper catalog and is intentionally excluded from Transactional Multi API because it performs network I/O.
Physical Package freshness fields are optional and backward compatible. Package creation, barcode acceptance, Put Away, and Product Photo Review may submit date_type, date_precision, date_year, date_month, date_day, and date_other_label; omission does not clear an existing date. POST /mobile/kitchen-inventory/{inventory_item_id}/package/{package_id}/expiration is the explicit Package-date mutation endpoint and accepts clear_date=true for intentional removal. Month/year precision is retained as month/year rather than materializing a synthetic day.
Data Purge remains outside Multi API even when triggered through API Tester. Scheduled retention now includes per-use-case terminal AI job/AI Usage/Seed-accounting cleanup, Social Recipe Import evidence compaction, and Regression Test Organization marker pruning; those operations intentionally span multiple domains and may own files/evidence outside the database transaction.
A mutation not in the verified set is not Multi-capable merely because it happens to use a database. Examples intentionally excluded include recipe create/save paths that write cache/source files, display content/render operations, backup/restore, email, credential generation/rotation, provider connection tests, background-job starts/retries, Recipe Discovery save, social candidate creation/retry, GeoIP/country-flag asset updates, and destructive archive/delete actions.
Explicit read-like exclusions
The read audit also keeps the following operations out of Multi API even though their registry operation is read-like:
- Recipe Discovery search, Noun Project connection test, cloud-backup status/download-check/connection-test, and external Recipe Share preview calls because they contact external systems.
- Full external Recipe Share payload retrieval because it also reserves share consumption.
- Recipe Share export and AI reconciliation CSV because they generate file responses; Recipe Share export can additionally send email when optional recipients are supplied.
- Display state, kiosk page, and remote-display client state/panel transport because they record access/heartbeat/polling state; kiosk recipe thumbnail is also a binary response.
/status/jobsbecause polling marks stale jobs failed before returning the list.- Meal Planner Meal Slot Summary and View Saved AI Meal Plan because they intentionally refresh source fingerprints and can mark a saved AI Meal Plan stale while building the response.
AI Meal Image Options is kept Multi-safe by remaining side-effect free: opening the options surface reads an existing Meal identity when present but does not create one. Identity creation occurs when the user actually starts generation or explicitly edits Meal metadata.
This explicit exclusion list prevents a future GET or read_only=True POST from becoming Multi-capable solely because of its HTTP method/registry flag.
Recipe Discovery dietary execution state
Recipe Discovery search, URL-preview, and save requests accept optional dietary_keys and dietary_custom_note fields. When those fields are omitted, Recipe Discovery starts from the organization's saved household/family defaults. When the client supplies them, they are a temporary operation snapshot carried through search → preview → save and do not update the organization settings. An explicit empty dietary_keys: [] means no built-in dietary restrictions for that discovery operation; it must not be interpreted as “fall back to organization defaults.” Automated discovery uses the active snapshot to shape search and detect obvious ingredient conflicts, while normal manual Recipe/Meal Planner entry remains available outside those defaults.
API Tester Multi API submission flow
The Multi API editor lists only endpoints whose live multi_api.eligible flag is true. Selecting a sub-API opens a guided operation editor that derives the method and route from the endpoint ID. Path/query parameter examples and defaults are prefilled when available; required path/query values are validated before the operation can be added.
Body fields are generated from the endpoint's request schema. Required properties are marked, booleans/numbers are type-aware, enums use selectors, and array/object fields use JSON-aware editors rather than being stringified. Raw JSON remains available for advanced editing, but it is parsed and checked against the selected endpoint schema before the operation is accepted. This is especially important for bulk APIs such as Cookbook Category recipe assignments, which require JSON arrays.
Recipe-creation schemas expose optional Cookbook Category public IDs where the corresponding transport supports initial assignment. JSON callers use cookbook_category_ids as an array; form/multipart adapters accept the equivalent JSON-array/comma-separated representation and normalize it server-side. Recipe Share file export documents Paprika, Schema.org JSON-LD, and Cooklang plus optional email_recipients, message, and sender_name. A blank recipient field produces the binary download even when message/sender are populated; one or more recipients switch the response to an email-result JSON payload and the artifact is emailed instead of downloaded. Because recipients make the operation capable of sending email, that export endpoint is treated as mutating for API Tester permission purposes even when a particular call leaves recipients blank.
Display receiver/render schemas in API Tester match the production forms: receiver refresh/status-bar/fit/background/kiosk-idle settings and timed Meal Planner/Let's Cook render settings. The generic Display Advanced Settings route is documented-only because it consumes dynamically registered display_setting__... fields and currently has no stable curated display-scoped submission schema.
The server still re-resolves every endpoint ID, permission, organization context, and Multi eligibility at execution time. Editing the generated JSON manually cannot bypass the registry assessment.
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
- Log in to Blackcap.
- Open
/api-tester. - Click the Postman button in the sidebar.
- Download the collection with Download Collection.
- Download the environment with Download Environment.
- Import both files into Postman.
- 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:
- Open
/api-testerwhile logged in. - Select the organization context you want the token to use.
- Click Postman.
- Click Copy Postman Token and paste it into the
blackcap_postman_tokenenvironment 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/usageGET /admin/ai/usage/reconciliation.csvfor System AdminsGET /admin/ai/organizations/{organization_id}/drupeletesGET /admin/ai/organizations/{organization_id}/drupeletes/adjustmentsGET /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-urlencodedfields - 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.
Recipe Discovery dietary execution state
Recipe Discovery search, URL-preview, and save requests accept optional dietary_keys and dietary_custom_note fields. When those fields are omitted, Recipe Discovery starts from the organization's saved household/family defaults. When the client supplies them, they are a temporary operation snapshot carried through search → preview → save and do not update the organization settings. An explicit empty dietary_keys: [] means no built-in dietary restrictions for that discovery operation; it must not be interpreted as “fall back to organization defaults.” Automated discovery uses the active snapshot to shape search and detect obvious ingredient conflicts, while normal manual Recipe/Meal Planner entry remains available outside those defaults.
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_tokenandblackcap_api_tokenwhen 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.