Hub Import API
28 min
purple hub api request the purple hub offers a rest api for importing articles with all connected metadata for each hub cluster, this data is required to perform the call data description example hub cluster domain determines the hub cluster, data is imported to demo purpledshub com hub identifier determines the hub instance, data is imported to my news portal authorization token securing the call to import data 4de214ac cfdb 2154 11f2 10470a4bb5f1 publication id references the feed, data is imported to 3bca5bf2 425a 47ac 93f9 135ce05e117d the call is performed with the parameters above request post https //\<hub cluster domain>/\<hub identifier>/wp json/purple/v3/import headers authorization bearer \<authorization token> post parameters post \<post data> where post data is a json structure containing post content and metadata the publication id is also part of the post data, as outlined below important the externalid is unique, meaning that if a post with an externalid already exists, this one will overwritten when sending another request with the same externalid accordingly, also the post type etc will be overwritten authentication to retrieve a token you need to call the post /\<hub identifier>/wp json/purple/v3/login endpoint the body needs to include the following parameters as json body field description username your username password your password as a response you receive a token that can be used as authorization token when calling the export api json structure of “post” parameter { "externalid" "\<external uuid>", "post" { "title" "\<title>", "type" "post", "date" "\<publish date, format 2023 01 01t00 00 00+01 00>", "slug" "\<slug>", "description" "\<summary/onlineteaser>", "content" "\<html content>" }, "assets" \[ "\<asset url 1>", "\<asset url 2>", ], "meta" { "key" "value", "key1" "value", }, "acf" { "overline" "\<overline>", "isins" \[ { "item" "\<isin 1>" }, { "item" "\<isin 2>" }, ], "serie" "\<series>", "stadt" "\<city>", }, "taxonomies" { "category" \[ { "name" "\<main section>" } ] "post tag" \[ "\<keyword 1>", "\<keyword 2>", ], }, "authors" \[ "\<author 1>", "\<author 2>", ], "publish" { "publicationid" "\<publication id>", "release" true, // check the hub settings for your configured access levels and use the index as it configured there "paywall" <0=free, 1=paid, 2=kompakt> // default, check for your hub as described above }, // the accesslevel parameter is prioritized over the "publish" >"paywall" parameter "accesslevel" <0=free, 1=paid, 2=kompakt> // default, check for your hub as described above } the property „assets“ is a list of urls referencing assets (images, etc ) that appear in the content and have to be copied to the purple hub please note the externalid that is set during the hub import is not the externalid exposed in the catalogapi/content cloud the externalid available in the catalogapi is the wordpress post id whereas the externalid for the hub import api is only used during the import and is not stored in the hub or in the count cloud example for a “post” parameter { "externalid" "3c6fcf10 0f6c 11ed a8b4 07f9801ba5be", "post" { "title" "does my dog love me? here’s how to know for sure", "type" "post", "date" "2022 08 02t00 00 00+01 00", "slug" "does my dog love me heres how to know for sure", "description" "sure, they wag their tails to greet us and are happy to snuggle up and watch tv in the evening ", "content" "\<! wp\ paragraph >\<p>sure, they wag their tails to greet us and are happy \<! /wp\ paragraph >", "status" "draft" }, "assets" \[], "acf" { "custom field" "value", "custom array" \[{ "item" "item 1" }, { "item" "item 2" } ] }, "taxonomies" { "category" \[{ "name" "category 1" }], "post tag" \[{ "name" "tag 1" }, { "name" "tag 2" } ] }, "authors" \["jack author"], "publish" { "publicationid" "3bca5bf2 425a 47ac 93f9 135ce05e117d", "release" true, "paywall" 1 } } structure html content the actual content structure is reflected by the code view of the article in the purple hub, except for any unique purpleid attribute, which is not expected to be given response codes and messages response for a succeeded call 200 \<post id> responses for erroneous calls 400 an unexpected error occurred while updating/inserting post \<error> 401 no authorization token was provided 401 the authorization token is incorrect 400 no json string was provided 400 could not decode json please check if the provded json is valid 400 the json string contains no data nothing to do 400 missing post data 400 missing post title 400 missing post status 400 the provided post status does not exist 400 missing post type 400 the provided post type does not exist image focal points focal point management is handled by the "smart media" plugin, and stored as post meta by the hub import api for that plugin to use the coordinates are given in pixels from the top left corer of an image focal points can be set for the featured image of a post, as well as for the "assets" given alongside of it in the json both kinds of images need to be given in object form (instead of only the url string), and then the focal point can be given as in a separate property see also the schema document below { "url" "https //example com/image jpg", "focalpoint" { "x" 380, "y" 180 } } images in acf properties if an acf property should be set to reference an imported image, the special syntax "$assetidfromurl" can be used in the value for this field during post import, the database field will then store the id of the image imported from this url, so that acf image fields work correctly additional information about this image (like caption, or even further acf properties for the image itself) can be defined in the assets section as usual { "post" { "title" "article with acf image" }, "acf" { "myimageacffield" { "$assetidfromurl" "https //placehold co/100 jpg" } }, "assets" \[ { "url" "https //placehold co/100 jpg", "caption" "an example image caption", "acf" { "myimagecopyrightfield" "cc by placehold co" } } ] } duplicate images per language as default, the importer compares imported images on a hash level to avoid images being imported multiple times however, if your hub is using multiple languages, you might want to have image duplicates on a language level to be able to keep metadata as for example the description or caption for each language separate this is possible with the following syntax { "post" { "title" "it article with featured image duplicated", "language slug" "it", "featuredimage" { "url" "https //http cat/200 jpg" } }, "duplicateassetsbylanguage" true } \ { "post" { "title" "de article with featured image duplicated", "language slug" "de", "featuredimage" { "url" "https //http cat/200 jpg" } }, "duplicateassetsbylanguage" true } in this example, the image gets imported twice, once in italian and once in german and both images get connected to each other the feature gets activated by setting the "duplicateassetsbylanguage" flag to true note that this only works when also the "language slug" for the post is set schema for validating the api input in order to make sure, that the input transferred through the api is correct, please use this json schema attached here as a download update posts to update posts, send another call to the same endpoint if an existing post is found with the same external id (or the same title if no external id is given), this one will be updated, instead of a new one being created remove featured image to remove the featured image of an existing post, send an update request, and set the url of the featured image to an empty string other updates (like the post content) can be made with the same request { "post" { "title" "existing article with featured image", "type" "post", "featuredimage" { "url" "" } } } remove acf value if you want to remove the value of an acf field, you need to set an update request and set an empty string as value { "post" { "title" "existing article with featured image", "type" "post", "acf" { "imagefield" "" } } } delete posts the importer api can also be used to delete and unpublish posts posts are automatically unpublished when they are deleted from the hub following parameters can be used postid required if externalid isn't set, otherwise optional id of the post in the hub externalid optional externalid that was used when the post was imported if both postid and externalid are set, the externalid is used deletepermanently optional set to true to permanently delete a post if not set or set to false, posts are only moved to trash request post https //\<hub cluster domain>/\<hub identifier>/wp json/purple/v3/import /delete possible error codes 400 missing parameters neither postid nor externalid are set 400 post not found no post is found with the given id 500 failed to delete post an error occurred during the deletion of the post example of the body for a delete call { 	"postid" 77289, 	"externalid" "s34dgfd sdfdsf", // externalid is used in this example 	"deletepermanently" true } linking variants on import when the purple variants plugin is active (see also purple variants docid\ vvouzgcviehksoaroz9nu ), you can link imported posts as content variants of one another using the optional variantof field the first post must be imported without variantof subsequent posts that should belong to the same variant group reference the already imported post // reference by the wordpress post id returned from a previous import call { , "variantof" { "postid" 1234 } } // reference by the externalid of the previously imported post { , "variantof" { "externalid" "article web v1" } } any post in the variant group can serve as the reference target — you do not need to reference the first post specifically removing a post from its variant group pass null to disconnect the post from all variants on an update call { , "variantof" null } the variantof field only manages the variant group connection it does not create or modify any post content or metadata — that is handled by the import data itself importing dossiers dossiers ( purple dossier ) can be created and populated via the import api the typical workflow consists of three steps create the dossier by importing a post with "type" "purple dossier" import articles and link them to the dossier via the addtodossiers field publish the dossier (optional) once all articles are in place step 1 create the dossier { "post" { "title" "my dossier", "slug" "my dossier", "type" "purple dossier", "status" "draft", "content" "\<p>this is the dossier title page \</p>" } } the response returns the wordpress post id of the newly created dossier use this id when importing articles in the next step step 2 import articles and add them to the dossier use the addtodossiers field to link an article to one or more existing dossiers by their wordpress post ids { "post" { "title" "my article", "type" "post", "slug" "my article", "content" "\<p>article content here \</p>" }, "addtodossiers" \[12345] } addtodossiers accepts an array of ids, so one article can be added to multiple dossiers in a single call step 3 publish the dossier (optional) after all articles are imported, publish the dossier by referencing it via its slug { "post" { "slug" "my dossier" }, "publish" { "release" true } } importing taxonomy terms directly when importing a post, terms (like categories, tags, or custom taxonomy terms) can be imported as well within that payload, via the taxonomy property alternatively, terms can also be imported on their own, without a post that uses them instead of calling the /wp json/purple/v3/import endpoint, call /wp json/purple/v3/import/term the payload needs at least two fields one for the name of the taxonomy that the term belongs to, and one for the term data itself the data format is the same as for the list of taxonomy terms in the post import endpoint { "taxonomy" "category", "term" { "name" "my example category term", "acf" { "myacffield" "example acf value" } } } similar to the post import endpoint, if a term with this name / slug already exists, no new term is created, but the existing term is updated instead the endpoint returns the id of the (freshly created) term when using the post import endpoint later, instead of re sending the whole set of information for a term that should be linked to this post, the endpoint also accepts this id image acf properties for terms it is possible to import images used in terms with this term import endpoint, using the same syntax as for the post import endpoint { "taxonomy" "my custom taxonomy", "term" { "name" "example term with image acf", "acf" { "myimage" { "$assetidfromurl" "https //http cat/305 jpg" } } }, "assets" \[ { "url" "https //http cat/305 jpg", "acf" { "myacffieldonimages" "example image acf value" } } ] } as usual, if the url passed to "$assetidfromurl" was already imported previously, this existing imported image gets linked to the term if not, the image gets imported into the hub via the "assets" field, additional information about the used images can be provided, like acf fields for the images themselves