WARNING: If you are reading this on GitHub, DON’T! Read it on ReadTheDocs:
references and proper formatting.


Create content

First get the portal object that we will use as a container for new content:

from plone import api
portal = api.portal.get()

If you want to create a new content item, use the api.content.create() method. The type attribute will automatically decide which content type (dexterity, archetype, ...) should be created.

from plone import api
obj = api.content.create(
    title='My Content',

The id of the object gets generated (in a safe way) from its title.

assert obj.id == 'my-content'

Get content object

There are several approaches of getting to your content object. Consider the following portal structure:

plone (portal root)
|-- blog
|-- about
|   |-- team
|   `-- contact
`-- events
    |-- training
    |-- conference
    `-- sprint

You can do the following operations to get to various content objects in the stucture above, including using api.content.get().

# let's first get the portal object
from plone import api
portal = api.portal.get()
assert portal.id == 'plone'

# content can be accessed directly with dict-like access
blog = portal['blog']

# another way is to use ``get()`` method and pass it a path
about = api.content.get(path='/about')

# more examples
conference = portal['events']['conference']
sprint = api.content.get(path='/events/sprint')

# moreover, you can access content by it's UID
uid = about['team'].UID()
conference = api.content.get(UID=uid)

Find content object

You can use the catalog to search for content. Here is a simple example:

from plone import api
catalog = api.portal.get_tool(name='portal_catalog')
documents = catalog(portal_type='Document')

More about how to use the catalog and what parameters it supports is written in the Collective Developer Documentation. Note that the catalog returns brains (metadata stored in indexes) and not objects. However, calling getObject() on brains does in fact give you the object.

document_brain = documents[0]
document_obj = document_brain.getObject()
assert document_obj.__class__.__name__ == 'ATDocument'

Get content object UUID

An Universally Unique IDentifier (UUID) is a unique, non-human-readable identifier for a content object which stays on the object even if the object is moved.

Plone uses UUIDs for storing content-to-content references and for linking by UIDs, enabling persistent links.

To get a content object UUID use api.content.get_uuid(). The following code gets the UUID of the contact document.

from plone import api
portal = api.portal.get()
contact = portal['about']['contact']

uuid = api.content.get_uuid(obj=contact)

Move content

To move content around the portal structure defined above use api.content.move() The code below moves the contact item (with all objects that it contains) out of folder about into the Plone portal root.

from plone import api
portal = api.portal.get()
contact = portal['about']['contact']

api.content.move(source=contact, target=portal)

Actually, move behaves like a filesystem move. If you pass it an id argument, you can define to what target ID the object will be moved to. Otherwise it will be moved with the same ID that it had.

Rename content

To rename, use the api.content.rename() method.

from plone import api
portal = api.portal.get()
api.content.rename(obj=portal['blog'], new_id='old-blog')

Copy content

To copy a content object, use the api.content.copy().

from plone import api
portal = api.portal.get()
training = portal['events']['training']

api.content.copy(source=training, target=portal)

Note that the new object will have the same id as the old object (if not stated otherwise). This is not a problem, since the new object is in a different container.

You can also set target to source’s container and set safe_id=True which will duplicate your content object in the same container and assign it a non-conflicting id.

api.content.copy(source=portal['training'], target=portal, safe_id=True)
new_training = portal['copy_of_training']

Delete content

Deleting content works by passing the object you want to delete to the api.content.delete() method:

from plone import api
portal = api.portal.get()

Content manipulation with the safe_id option

When manipulating content with api.content.create(), api.content.move() and api.content.copy() the safe_id flag is disabled by default. This means the id will be enforced, if the id is taken on the target container the API method will raise an error.

However, if the safe_id option is enabled, a non-conflicting id will be created.

api.content.create(container=portal, type='Document', id='document', safe_id=True)
document = portal['document-1']

Get workflow state

To find out in which workflow state your content is, use api.content.get_state().

from plone import api
portal = api.portal.get()
state = api.content.get_state(obj=portal['about'])


To transition your content into a new state, use api.content.transition().

from plone import api
portal = api.portal.get()
state = api.content.transition(obj=portal['about'], transition='publish')

Get view

To get a BrowserView for your content, use api.content.get_view().

from plone import api
portal = api.portal.get()
view = api.content.get_view(

Further reading

For more information on possible flags and usage options please see the full plone.api.content specification.

Project Versions

Table Of Contents

Previous topic


Next topic


This Page