Sync Component

Authentication: JWT | API Key

Collections can embed Components via nested fields. When a nested field is pinned (auto_update: false), its component_version is frozen and does not advance automatically when the Component publishes a new version. The sync_component endpoint lets you explicitly advance one or more pinned nested fields to a target Component version — either the Component's current published version or any specific version you specify.

Use this endpoint to:

  • Upgrade pinned nested fields to a newer Component version after reviewing the changelog.
  • Roll back a pinned nested field to an earlier Component version.
  • Advance a batch of pinned fields across the Collection schema in a single request.

See Composing Components on the Collections page for a conceptual overview of auto_update vs. pinned mode, and Components for the live-link model behind reusable schemas.

Path Parameters

  • Name
    :env
    Type
    string
    Description

    Unique identifier of the environment.

  • Name
    :collection
    Type
    string
    Description

    Unique identifier (key) of the Collection whose nested fields should be advanced.

POSTapi.foxnose.net/v1/:env/collections/:collection/sync_component/

Sync Component

Advances pinned (auto_update: false) nested fields on a Collection to a specified Component version, or to each Component's current_version when no explicit target is supplied.

The endpoint creates a new published Collection schema version in place — no draft handoff is required. The previous published version is archived automatically; existing Revisions remain bound to it.

All fields in the request body are optional. Sending an empty body ({}) advances every pinned nested field in the Collection schema to its Component's current published version.

Success Response: 200 OK

Request Body

  • Name
    field_paths
    Type
    array of strings
    Description

    List of dot-delimited nested field paths to advance (e.g., ["hero", "sidebar.widget"]).

    • When omitted, all pinned nested fields in the Collection schema are targeted.
    • Paths that refer to auto_update: true fields are reported in skipped with reason auto_update_mode.
    • Paths that don't match any nested field on the current Collection version are NOT reported (the loop iterates over actual nested fields, not the request).
  • Name
    to_versions
    Type
    object
    Description

    Per-path override of the target Component version. Keys are field paths; values are Component version UIDs.

    {
  "hero": "cv_Xk2mP9nQrTvZ",
  "sidebar.widget": "cv_Ab3cD4eF5gHi"
}
    • When a path is omitted from to_versions, that field advances to its Component's current_version.
    • When both field_paths and to_versions are supplied, every key in to_versions must also appear in field_paths.
    • Specifying a version UID that does not exist results in a 404 resource_not_found error.

Response Body (200 OK)

  • Name
    synced_paths
    Type
    array of strings
    Description

    Field paths that were successfully advanced to a new Component version.

  • Name
    skipped
    Type
    array of objects
    Description

    Fields that were targeted but not advanced. Each entry has:

    • path (string) — the field path that was skipped.
    • reason (string) — why the field was skipped. Possible values:
      • not_requested — field_paths was supplied and this path was not in it.
      • auto_update_mode — the field has meta.auto_update=true; only sync_component on pinned (auto_update=false) fields.
      • already_at_target — the field is already pinned to the requested target version.
      • component_not_found — the field's referenced Component does not exist in this environment.
      • component_unpublished — the Component has no published current_version to advance to.
  • Name
    schema_version
    Type
    string
    Description

    UID of the new published Collection schema version created by the sync. null when no field was advanced (every requested path was skipped).

Required Permissions

  • Name
    collection-schemas:update
    Description

    Must be granted on the target Collection.

  • Name
    folder-items:read
    Description

    Must be granted on the target Collection.

  • Name
    components:read
    Description

    Must be granted on every Component referenced by a pinned nested field being synced.

Errors

  • Name
    401 Unauthorized
    Description

    Authentication credentials are missing or invalid.

    • authentication_failed — credentials were not provided or are invalid.
  • Name
    403 Forbidden
    Description

    Insufficient permissions to perform this operation.

    • permission_denied — one or more required permissions are missing.
  • Name
    404 Not Found
    Description

    A referenced resource could not be found.

    • resource_not_found — the Collection does not exist, or a version UID supplied in to_versions does not match any published Component version.
  • Name
    409 Conflict
    Description

    One or more fields cannot be advanced because the target Component version introduces schema changes that are incompatible with the Collection's existing data.

    • component_sync_conflict — the response body includes a detail.conflicts array, where each entry has:
      • field_path (string) — the nested field path that has a conflict.
      • blocking_reason (string) — the nature of the incompatibility. Possible values:
        • required_field_added_no_default — the target version adds a required field that has no default value, which would invalidate existing resources.
        • type_narrowed — the target version narrows a field's type in a way that existing data may not satisfy.
        • field_removed — the target version removes a field that is present in existing resources.
  • Name
    422 Unprocessable Content
    Description

    Validation or business logic error.

    • validation_error — the request body is malformed (e.g., a to_versions key is not present in field_paths).
    • too_many_versions — advancing the fields would exceed the Collection's schema version quota. Archive or delete old versions before retrying.

Request

POST
/v1/:env/collections/:collection/sync_component/
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/sync_component/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{}'

Response 200

{
    "synced_paths": ["hero", "sidebar.widget"],
    "skipped": [],
    "schema_version": "vr8x2k9m"
}

Response 409 (conflict)

{
    "message": "Sync blocked by 1 compatibility conflict(s).",
    "error_code": "component_sync_conflict",
    "detail": {
        "conflicts": [
            {
                "field_path": "hero",
                "blocking_reason": "required_field_added_no_default"
            }
        ]
    }
}

Response 422 (quota)

{
    "message": "Too many versions for this schema",
    "error_code": "too_many_versions",
    "detail": null
}

Was this page helpful?