Content

Note: as with all of our other endpoints, our API is self-documenting. All of the functionality and information that we offer is accessible via requests made to our template endpoints.

In Cerkl terms, "Content" means Events, Stories, Needs, and Links added to your Cerkl instance by users or external RSS or Atom feeds. Content appears to your Subscribers in their personalized Newsletters, which present them with the types of Content (based on Categories) they're most interested in.

Programmatically, each of these types of Content can be added, updated, and deleted using their own endpoints (e.g. POST a Story using /story, PUT, or DELETE a Story using /story/{id}). However, to GET Content, you must use the /content endpoint to retrieve all of the Content in a Cerkl and /content/{id} to retrieve a certain piece of Content specified by its Cerkl id.

For example, if you've authenticated with a Cerkl instance, you can get all of its content like this:

$ curl --request GET https://api.cerkl.com/v3/content \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'

Remember: all Cerkl GET endpoints that don't target specific id values function as "GET all" requests. As with all of our other "GET all" functionality, you can specify page (defaults to 1) and page_size (defaults to 100) parameters to control the amount of information returned to you.

$ curl --request GET https://api.cerkl.com/v3/content \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    -G -d page=1 -d page_size=100

Adding and Updating Content

As mentioned above, you will need to use the specific endpoints associated with each type of Content in order to perform create (POST), update (PUT), and delete (DELETE) operations. See the Events, Stories, and Needs sections for information on using those specific endpoints.

Content Insights

Because Cerkl gathers data about how Subscribers interact with Content, you can also query the Insights for a particular Content piece. For more information, see our Insights documentation.

Content Types

Stories

Stories are articles that you are presenting to your Cerkl Subscribers. These can include company-wide communications that you want to appear in your Subscribers' personalized newsletters and articles you think different people in your Audience might find interesting.

Adding Stories

To add Stories, POST to the /story endpoint:

$ curl --request POST 'api.cerkl.com/v3/story' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "3.0",
            "data": [
            {
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "publish_date_utc": "string",
                "expiration_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "evergreen": <bool>,
                "self": "string"
            }
        ]
    }
}'

Retrieving Stories

Stories are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Story Content).

Updating Stories

To update an existing Story, utilize the PUT method on the /story/{id} endpoint, constructing your URL with the id of the existing Story. If your Story's ID is 12345, that looks like this:

$ curl --request PUT 'api.cerkl.com/v3/story/12345' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "3.0",
            "data": [
            {
                "id": <integer>,
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "publish_date_utc": "string",
                "expiration_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "evergreen": <bool>,
                "self": "string"
            }
        ]
    }
}'

Deleting Stories

To delete an Story, you just need to make a DELETE request to the Story/{id} endpoint using the id corresponding to your Story. If our Story id is still 12345 as it was above, that looks like this:

$ curl --location --request DELETE 'api.cerkl.com/v3/story/12345' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'

Events

Event Content represents an upcoming event that you would like to announce to your Cerkl Subscribers in their Newsletters. Events include information about the Event location, start and end times, and links to any registration links your Subscribers need to know about.

Adding Events

To add Events, POST to the /event endpoint:

$ curl --request POST 'api.cerkl.com/v3/event' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "string",
            "data": [
            {
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "event_location": "string",
                "event_street_address": "string",
                "event_city": "string",
                "event_postal_code": "string",
                "event_region": "string",
                "event_country": "string",
                "event_all_day": <bool>,
                "event_start_date_time_utc": "string",
                "event_end_date_time_utc": "string",
                "event_time_zone": {
                    "id": <integer>,
                    "self": "string"
                },
                "event_registration_url": "string",
                "external_url": "string",
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "self": "string"
              }
            ]
        }
    }'

Retrieving Events

Events are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Event Content).

Updating Events

To update an existing Event, utilize the PUT method on the /event/{id} endpoint, constructing your URL with the id of the existing event. If your Event's ID is 12345, that looks like this:

$ curl --request PUT 'api.cerkl.com/v3/event/12345' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "3.0",
            "data": [
            {
                "id": <integer>,
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>
                },
                "priority_until_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "event_location": "string",
                "event_street_address": "string",
                "event_city": "string",
                "event_postal_code": "string",
                "event_region": "string",
                "event_country": "string",
                "event_all_day": <bool>,
                "event_start_date_time_utc": "string",
                "event_end_date_time_utc": "string",
                "event_time_zone": {
                    "id": <integer>,
                    "self": "string"
                },
                "event_registration_url": "string",
                "external_url": "string",
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "self": "string"
            }
        ]
    }
}'

Deleting Events

To delete an Event, you just need to make a DELETE request to the event/{id} endpoint using the id corresponding to your Event. If our Event id is still 12345 as it was above, that looks like this:

$ curl --location --request DELETE 'api.cerkl.com/v3/event/12345' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'

Links

Link Content allows you to link external articles (from other websites and CRMs) to Cerkl. Links behave very similarly to Stories, but they let the external URL do most of the work for you. When other content is linked with a

Adding Links

To add Links, POST to the /link endpoint:

$ curl --request POST 'api.cerkl.com/v3/link' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "3.0",
            "data": [
            {
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "external_url": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "publish_date_utc": "string",
                "expiration_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "evergreen": <bool>,
                "self": "string"
            }
        ]
    }
}'

Retrieving Links

Links are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Link Content).

Updating Links

To update an existing Link, utilize the PUT method on the /link/{id} endpoint, constructing your URL with the id of the existing Link. If your Link's ID is 12345, that looks like this:

$ curl --request PUT 'api.cerkl.com/v3/link/12345' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "3.0",
            "data": [
            {
                "id": <integer>,
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "external_url": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "publish_date_utc": "string",
                "expiration_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "evergreen": <bool>,
                "self": "string"
            }
        ]
    }
}'

Deleting Links

To delete a Link, you just need to make a DELETE request to the link/{id} endpoint using the id corresponding to your Link. If our Link id is still 12345 as it was above, that looks like this:

$ curl --location --request DELETE 'api.cerkl.com/v3/link/12345' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'

Needs

Needs are Content your Cerkl users (the people creating Content) can use to request things from your Subscribers. The quantity of whatever is needed (e.g. participants, donations, etc.) and the need_by_date_utc can be specified to be more specific about what is being requested.

Adding Needs

To add Needs, POST to the /need endpoint:

$ curl --request POST 'api.cerkl.com/v3/need' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "3.0",
            "data": [
                {
                "author": {
                    "id": <integer>
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "publish_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "need_quantity": 0,
                "need_by_date_utc": "string",
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "self": "string"
            }
        ]
    }
}'

Retrieving Needs

Needs are pieces of Content, and can be retrieved using the GET method on the /content or /content/{id} endpoints (depending on whether you need all Content or just the specific Need Content).

Updating Needs

To update an existing Need, utilize the PUT method on the /need/{id} endpoint, constructing your URL with the id of the existing Need. If your Need's ID is 12345, that looks like this:

$ curl --request PUT 'api.cerkl.com/v3/need/12345' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}' \
    --data-raw '{
        "template": {
            "version": "string",
            "data": [
            {
                "id": <integer>,
                "author": {
                    "id": <integer>,
                    "self": "string"
                },
                "title": "string",
                "summary": "string",
                "body": "string",
                "more_button_text": "string",
                "image_url": "string",
                "categories": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "external_id": "string",
                "priority": {
                    "id": <integer>,
                    "self": "string"
                },
                "priority_until_date_utc": "string",
                "private": <bool>,
                "segments": [
                    {
                        "id": <integer>,
                        "self": "string"
                    }
                ],
                "exclusive_to_segment": <bool>,
                "available_in_aptly": <bool>,
                "enable_comments": <bool>,
                "enable_link_tracking": <bool>,
                "external_url": "string",
                "status": {
                    "id": <integer>,
                    "self": "string"
                },
                "self": "string"
              }
            ]
        }
    }'

Deleting Needs

To delete an Need, you just need to make a DELETE request to the need/{id} endpoint using the id corresponding to your Need. If our Need id is still 12345 as it was above, that looks like this:

$ curl --location --request DELETE 'api.cerkl.com/v3/need/12345' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'