edit-content

Create and edit content in Agility CMS

Find the target

• Confirm the instance and locale. Call get_locales if the locale has not been settled in this conversation. Content is per locale: saving to the wrong locale creates a separate item.
• To find an item by text, title or ID, call search_instance. If search is not available for the instance, call get_containers and then get_content_items for the right container. Do not retry search repeatedly.
• Before writing, call get_content_model_details for the container's model. Use the real field names, types and required fields. Ask the user for required values you do not have; do not invent them.

Create a new item

1. Call save_content_items with contentID: -1, the container's referenceName, the locale, and the fields.
2. Read the result. It gives the new contentID and an editUrl for each item.
3. Call get_content_item with that contentID to confirm the saved values. A brand-new draft can be missing from get_content_items lists for a short time; reading it by ID is reliable.
4. Tell the user the item is saved as a draft (not published) and give them the actual editUrl from the result.

Update an existing item

1. Call get_content_item first. Note every field value and properties.versionID.
2. Call save_content_items with the item's contentID, all of its fields (changed and unchanged), and properties.versionID set to the current version. Fields you leave out are wiped.
3. Read the item back with get_content_item and confirm that only the intended fields changed.

If you no longer know which item to update, ask. Never guess a content ID.

Field formats

• Links: {href, text, target}. Links inside the site use the ~/ prefix, for example ~/about-us.
• Linked content (dropdowns and lists that point at other items): use the exact companion field names shown by get_content_model_details, and real content IDs read from the linked container.
• Images and attachments: the field value is {url, label}.
  • To use an asset already in Agility, call list_media to find it and use its URL.
  • To add a new file the user has provided, call initialize_media_upload, POST the file to the returned uploadUrl within 5 minutes, and use the asset URL that the upload returns.
  • When updating an item, keep the existing URL for attachments that are not changing.
• SEO and GEO fields only apply to items in a dynamic page list (a container whose items each generate a page). Leave them out for ordinary containers.
• Release and pull dates: send releaseDate: null and pullDate: null unless the user is deliberately scheduling. A pull date in the past hides the item from the live site as soon as it is published. Dates are read as US Eastern time, so a date that looks a few hours ahead can already be past. Never copy dates from another item.
• Workflow state cannot be set by saving. Every save lands in the instance's default state, usually Staging. Publishing is a separate step; see the publish-and-workflow skill.