Ensure full product (config-as-code converge of the whole FPO)

POST

/v1/products/ensure-fpo

POST

/v1/products/ensure-fpo

$ curl -X POST https://api.runtype.com/v1/products/ensure-fpo \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "fpo": {}
> }'

1 {
2   "contentHash": "a3f5c9d8e7b4f1a2c6d8e9f0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
3   "entities": [
4     {
5       "kind": "product",
6       "name": "SmartHome Controller",
7       "ref": "smart_home_controller",
8       "result": "failed",
9       "error": "Failed to connect to capability backing flow",
10       "id": "prod-12345"
11     },
12     {
13       "kind": "flow",
14       "name": "Device Sync Flow",
15       "ref": "device_sync_flow",
16       "result": "created",
17       "error": "",
18       "id": "flow-67890"
19     },
20     {
21       "kind": "agent",
22       "name": "Notification Agent",
23       "ref": "notification_agent",
24       "result": "updated",
25       "error": "",
26       "id": "agent-54321"
27     },
28     {
29       "kind": "capability",
30       "name": "Voice Control",
31       "ref": "voice_control",
32       "result": "unchanged",
33       "error": "",
34       "id": "cap-98765"
35     }
36   ],
37   "hasFailures": true,
38   "result": "converged",
39   "productId": "prod-12345"
40 }

Idempotently converge an entire Full Product Object (the nested product graph) in one shot. Fans out to the per-entity ensure services in dependency order (product → capability backing flows/agents → capability links), returning a per-entity report. Identity is the product name + account scope. NON-atomic by design: a per-entity failure is reported in entities[].result = "failed" (and hasFailures) and a re-run self-heals; only a top-level product reject aborts. Set dryRun to plan without writing. PR1 scope: surfaces/records/schedules/secrets and capability-as-tool composition are not yet converged.

Idempotently converge an entire Full Product Object (the nested product graph) in one shot. Fans out to the per-entity ensure services in dependency order (product → capability backing flows/agents → capability links), returning a per-entity report. Identity is the product name + account scope. NON-atomic by design: a per-entity failure is reported in `entities[].result = "failed"` (and `hasFailures`) and a re-run self-heals; only a top-level product reject aborts. Set dryRun to plan without writing. PR1 scope: surfaces/records/schedules/secrets and capability-as-tool composition are not yet converged.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

fpomap from strings to anyRequired

A complete Full Product Object (FPO): the nested product graph (product, capabilities, tools, surfaces, …). Validated server-side via the shared FPO validator.

dryRunbooleanOptional

Plan without writing — returns a per-entity plan (CI drift gate).

onConflictenumOptional

Per nested entity: “overwrite” converges over dashboard/API edits.

Allowed values:

Response

Converge result: unchanged | converged | plan (dryRun), with a per-entity report.

contentHashstring

Server-computed canonical whole-FPO content hash.

entitieslist of objects

hasFailuresboolean

True when one or more entities failed to converge (re-run to self-heal).

resultenum

unchanged when every entity was unchanged, converged when at least one was created/updated, plan for dryRun.

productIdstring

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error