Skip to main content

Custom Entity by Slug

Endpoint Overview​

  • Endpoint Name: Custom Entity by Slug
  • Purpose: Retrieves the detail of a published custom entity for a specific culture, given its slug.
  • Method: GET
  • URL: /{version}/content/{culture}/{distributionCode}/{slug}

Authentication​

  • Authentication Type: None

Request​

Headers​

Header NameRequiredDescription
acceptYesapplication/json

Path Parameters​

ParameterTypeDescription
versionstringThe version of the API to be used. Allowed values: v2.
culturestringThe culture's identifier. E.g., en-us.
distributionCodestringThe type of entity to return, which corresponds to the value of the Distribution API Code field defined in the Custom Entities section, in the FORGE Back Office Administration panel.
slugstringThe language-specific identifier of the custom entity.

Response​

Response Codes​

HTTP Status CodeMeaning
200Successful request
404Not Found (resource does not exist)
500Internal Server Error

Response Body​

Data structure​

  • type: customentity (String)
  • _entityId: The language-independent unique identifier of the entity (Entity Code) (Guid)
  • _translationId: The language-specific unique identifier of the entity (Localized Entity Code) (Guid)
  • selfUrl: The URL to get the detail of this entity (String)
  • entityCode: The entity type code as configured on the Distribution API Code property on the Administration panel of FORGE back-office (String)
  • slug: The unique identifier of the entity (String)
  • title: The entity title (String)
  • tags: An array of objects containing the set of tags related to this entity (Array)
    • type: tag (String)
    • selfUrl: The URL to get the detail of the tag entity (String)
    • slug: The language-specific unique identifier of the tag bound to the entity (String)
    • neutralSlug: The language-independent unique identifier of the tag bound to the entity (String)
    • externalSourceName: The name of the external source from where the tag was selected. If null, the tag is of type free-text (String)
    • title: The title of the tag in the current language (String)
    • extraData: An object containing custom-defined data, bound to the current tag (Object)
    • fields: An object representing the available custom fields for the tag (Object)
  • relations: An array of objects containing the set of relations added to this entity (Array)

    ℹ️ From version 16.5.0, the related stories contain the field Headline.

  • references: An object containing the set of reference fields defined on this entity (Object)
  • fields: An object representing the available configured fields for this entity (Object)
  • createdBy: The full name of the author that created this entity (String)
  • lastUpdatedBy: The full name of the last author that updated this entity (String)
  • lastUpdatedDate: UTC timestamp of the last update operation occurred on this entity (Date-time)
  • contentDate: The UTC timestamp of this content (Date-time)
  • context: An object containing the information related to the tag used as the context (same contract as tag) (Object)
  • featured: When 1, it represents a promoted content (Integer)
  • thumbnail: An object representing the thumbnail of the picture bound to the current entity (Object)
    • title: The title of the photo (String)
    • templateUrl: The template URL that can be used to retrieve the photo file from Cloudinary (String). Contains {formatName} or {formatInstructions} placeholders. (String)
    • thumbnailUrl: The URL of the thumbnail format that can be used to retrieve the photo from Cloudinary (String)
    • format: The format of the original image (e.g., jpg, png, etc.) (String)
    • overriddenFormats: An object representing details related to the custom cropping coordinates set for this photo, if present. Available only when the system is configured with the cropping option (Object)
    • slug: The language-specific unique identifier of the photo entity used as the thumbnail (String)
    • selfUrl: The URL to get the detail of this entity (String)
  • _listAvailability: An integer with two possible values: 0 and 1.
    • When 0, it represents that the content is available in the list.
    • When 1, it represents unlisted content. (Integer)

Successful Response Example​

This sample assumes a custom entity type defined in FORGE with the Distribution API Code set as drivers.

Request GET https://acme.org/v2/content/en-us/drivers/lewis-hamilton

Response

▼ "root": {
▼ "pagination": {
"maxItems": 100
}
▼ "meta": {
"apiVersion": "2.0"
"generatedAt": "2020-07-28T15:32:22.6913306Z"
}
▼ "items": [
▼ "0": {
"type": "customentity"
"_translationId": "79f65781-cd23-4a50-a185-97e15244e2bf"
"_entityId": "2c2f1ac7-2637-4b25-823d-4c68e49e498c"
"selfUrl": "https://acme.org/v2/content/en-us/drivers/jacques-villeneuve"
"slug": "jacques-villeneuve"
"title": "Jacques Villeneuve"
▼ "tags": [
]
▼ "fields": {
"countryCode": "BRA"
"age": 49
"active": false
"points": 235
"wins": 11
"team": "williams"
"biography": "Judging by the record books Jacques Villeneuve had a Formula One career in reverse. He nearly won the driving title in his debut year, did so in his second season, then went steadily downhill and eventually dropped right out of the sport. Yet the statistical rise and fall of the son of one of the greatest racing heroes was not an accurate reflection of his driving ability, nor do the numbers do justice to his impact as one of the most colourful and controversial champions. As a distinctive personality he stood alone and in terms of his entertainment value he had few peers."
}
"createdBy": "Frank Becker"
"lastUpdatedBy": "Frank Becker"
"lastUpdatedDate": "2020-04-09T15:41:57.609Z"
"contentDate": "2020-04-09T15:41:57.609Z"
"featured": 0
"entityCode": "drivers"
}
▼ "1": {
"type": "customentity"
"_translationId": "e69e85eb-ab4f-4876-8a6e-d1a22eae2f0e"
"_entityId": "111b14d6-2d69-4256-b19a-e356c2dda04c"
"selfUrl": "https://acme.org/v2/content/en-us/drivers/lewis-hamilton"
"slug": "lewis-hamilton"
"title": "Lewis Hamilton"
▼ "tags": [
]
▼ "fields": {
"points": 3431
"wins": 84
"countryCode": "GB"
"team": "mercedes"
"biography": "‘Still I Rise’ – these are the words emblazoned across the back of Lewis Hamilton’s helmet and tattooed across his shoulders, and ever since annihilating expectations with one of the greatest rookie performances in F1 history in 2007, that’s literally all he’s done: risen to the top of the all-time pole positions list ahead of his hero Ayrton Senna, surged into second place in the wins column behind only the inimitable Michael Schumacher, and surpassed the legendary Sir Jackie Stewart for the most championship titles by a British driver.\n\nCould he be the G.O.A.T? Few would deny that he’s in the conversation – and what’s more he’s got there his way, twinning his relentless speed with a refusal to conform to stereotypes for how a racing driver should think, dress or behave. \n\nRespect is hard earned in F1, but Hamilton has it from every one of his peers. Why? Because they know that whatever the track, whatever the conditions, whatever the situation, when his visor goes down and the lights go out, it’s Hammertime."
"age": 35
"active": true
}
"createdBy": "Frank Becker"
"lastUpdatedBy": "Frank Becker"
"lastUpdatedDate": "2020-04-09T14:58:22.882Z"
"contentDate": "2020-04-06T09:31:37.721Z"
"featured": 0
▼ "thumbnail": {
"title": "1584013371803"
"templateUrl": "https://images.acme.org/media/image/private/{formatInstructions}/forge/mxacahu83w3gaydjnefz"
"thumbnailUrl": "https://images.acme.org/media/image/private/w_250,h_250,c_thumb,g_auto,q_auto,f_jpg/forge/mxacahu83w3gaydjnefz"
"format": "jpg"
▼ "overriddenFormats": {
}
"slug": "1584013371803"
"selfUrl": "https://acme.org/v2/content/en-us/photos/1584013371803"
}
"entityCode": "drivers"
}
▼ "2": {
"type": "customentity"
"_translationId": "e39e97eb-3c8f-442c-843c-61b85619d7b4"
"_entityId": "8a6f5db5-4a2d-42de-a502-fca8ab1f9cb0"
"selfUrl": "https://acme.org/v2/content/en-us/drivers/charles-leclerc"
"slug": "charles-leclerc"
"title": "Charles Leclerc"
▼ "tags": [
]
▼ "fields": {
"countryCode": "MCO"
"wins": 2
"points": 303
"age": 22
"team": "ferrari"
"biography": "Born in the Mediterranean idyll of Monaco, Leclerc arrived in F1 on a tidal wave of expectation. \n\nPractically peerless on his way to the GP3 and Formula 2 crowns, he showcased a dazzling array of skills from scorching pole positions, commanding victories – even when his car caught fire twice at Silverstone – to an ability to muscle his way through the pack. Winning back-to-back championships also taught Leclerc how to handle pressure, another useful tool in the big pond of Formula 1 racing. \n\nLeclerc may have quit school early, but he looks every inch the complete driver. World champions Lewis Hamilton and Sebastian Vettel have even gone on record to say Leclerc is the real deal – and it’s not often they agree on anything…\n\nStepping up to F1 in 2018, Leclerc showed flashes of ballistic pace on Saturdays and racing brilliance on Sundays, dragging his Sauber beyond its limits – and earning himself a money-can’t-buy race seat at Ferrari for 2019, stepping into the shoes of the Scuderia’s last world champion, Kimi Raikkonen. \n\nThere he immediately put the cat among the proverbial pigeons, unafraid to go wheel-to-wheel with established number one, Sebastian Vettel. A maiden F1 victory at Spa was followed by another a week later on Ferrari’s hallowed home turf of Monza. The tifosi had found another new hero – who then became the first man to out-score Vettel over a season with the Scuderia.\n\nOut of the car, Leclerc is modest and thoughtful - but then he is on his own very personal mission. This exciting young talent is racing for his late father Herve and his friend and mentor Jules Bianchi, the F1 driver who died in 2015. \n\nOn the evidence so far, he is doing them both proud."
"active": true
}
"createdBy": "Frank Becker"
"lastUpdatedBy": "Frank Becker"
"lastUpdatedDate": "2020-04-09T14:58:00.382Z"
"contentDate": "2020-04-06T09:28:59.971Z"
"featured": 0
▼ "thumbnail": {
"title": "1584013824254"
"templateUrl": "https://images.acme.org/media/image/private/{formatInstructions}/forge/hv8rbvqiaro2zkd7vuz5"
"thumbnailUrl": "https://images.acme.org/media/image/private/w_250,h_250,c_thumb,g_auto,q_auto,f_jpg/forge/hv8rbvqiaro2zkd7vuz5"
"format": "jpg"
▼ "overriddenFormats": {
}
"slug": "1584013824254"
"selfUrl": "https://acme.org/v2/content/en-us/photos/1584013824254"
}
"entityCode": "drivers"
}
▼ "3": {
"type": "customentity"
"_translationId": "6eb7cf7a-d690-4db4-aea6-14d4e03c7ae9"
"_entityId": "688b3fe0-f05f-4286-8aa0-0a549eae47f8"
"selfUrl": "https://acme.org/v2/content/en-us/drivers/sebastian-vettel"
"slug": "sebastian-vettel"
"title": "Sebastian Vettel"
▼ "tags": [
]
▼ "fields": {
"countryCode": "GER"
"team": "ferrari"
"wins": 53
"points": 2985
"age": 32
"biography": "Born and raised a Bull, but now very much a Prancing Horse, F1's poster boy of early achievement had won more than all but two drivers in history by the time he was just 26, including back-to-back world titles between 2010 and 2013.\n\nVettel’s trademark is pure pace – and of course his one-finger victory salute. In the chase to the chequered flag, he likes to lead from the front and just like his hero, Michael Schumacher, Vettel has settled in as a race-winning leader at Ferrari.\n\nBut for all his competitive streak, Vettel has a playful side too and has been known to let loose with a spot of Beatles karaoke - and baby can he drive a car. Alongside his four world crowns he can boast more than 50 pole positions and race victories, ranking him – statistically - above many of the biggest names in F1 history. No wonder then that he was hand-picked to return Grand Prix racing’s oldest team to glory. \n\nFollowing his move to Maranello, Vettel’s rivalry with Lewis Hamilton intensified. Opposites off track – Hamilton leading a glamorous public life while Vettel is a private family man – the duo have often been all too evenly matched on Sundays as they bid not just for more world titles, but to be hailed the best of their generation. \n\nBut now he faces an additional thorn in his side – young-gun team mate Charles Leclerc, the first man to outscore him over a season at the Scuderia - and Vettel will need to call on all his speed and experience if he’s to reassert himself over the ‘new boy’ in 2020."
"active": true
}
"createdBy": "Frank Becker"
"lastUpdatedBy": "Frank Becker"
"lastUpdatedDate": "2020-04-09T14:58:21.428Z"
"contentDate": "2020-04-06T09:27:10.798Z"
"featured": 0
▼ "thumbnail": {
"title": "1584013014200"
"templateUrl": "https://images.acme.org/media/image/private/{formatInstructions}/forge/ibpzduf8ew2gvj0xsulc"
"thumbnailUrl": "https://images.acme.org/media/image/private/w_250,h_250,c_thumb,g_auto,q_auto,f_jpg/forge/ibpzduf8ew2gvj0xsulc"
"format": "jpg"
▼ "overriddenFormats": {
}
"slug": "1584013014200"
"selfUrl": "https://acme.org/v2/content/en-us/photos/1584013014200"
}
"entityCode": "drivers"
}
]
}

Error Response Example​

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-bdd418da1652593248958acf2dfad4e0-6d55da45f17bddf1-00"
}

Common Errors and Troubleshooting​

Nothing known.