API Documentation

Please let us know about gaps or errors in our documentation at info@200ok.ch.

Let's begin with the 50'000ft view of alephDAM. It's a good entry point into understanding the basic concepts.

For ingesting data, alephDAM offers four protocols:

• FTP
• S3
• HTTP REST (push)
• HTTP Feeds (pull)

Content is stored as documents. Each document has a type indicating what kind of document it is. Here is a list of typical document types:

• article
• image-asset
• image
• video-asset
• video
• advisory

Let's first create a new article document. Here is a selection of properties that can be used when creating an article, for more options please refer to the API documentation available for your specified instances of alephDAM.

• identifiers, a list of identifiers (strings)
• title, the title of the article in plain text
• images, a list of images with the following properties
  • url, the url the image should be fetched from
  • caption, plain text
• type, the type of the document, here article
• language, the language of the article (ISO 639-1)
• text, the text of the article, either plain text or html, see details below
• catchline, the catchline of the article in plain text
• seo-title, the SEO title of the article in plain text
• seo-description, the SEO description of the article in plain text
• locations, a list of locations with the following properties:
  • type, either of city, area, or country
  • value, the name of the location in plain text
• paywall-state, e.g. free, metered, premium
• teaser, the teaser of the article in plain text

Text may be formatted as a HTML fragment. The root of the HTML fragment is expected to be either just HTML formatted text with no surrounding element, or a sequence (flat list) of paragraphs (p tags). Some target systems may support additional formattings like headlines and lists. Paragraphs may contain arbitrary HTML if the target system supports a Free-HTML-Component.

The first value in identifiers is the primary identifier, which is used to uniquely identify the article. Creating a new article with the same primary identifier will by default trigger an update of an already existing article. Although the effect depends on the defined workflow and the capabilities of the target systems.

http --ignore-stdin --pretty format \
  "${endpoint}/api/v1/${tenant}/documents?token=${auth_token}" \
  identifiers:="[\"$(uuidgen)\"]" \
  title="Demo Articel via API" \
  images:='[{"url": "https://200ok.ch/img/products/alephdam.png", "caption": "This is alephDAM"}]' \
  type="article" \
  language="de" \
  text="<p><strong>alephDAM</strong> is a modular Digital Asset Managment System and Streaming Platform.</p><p>This is the <em>2nd</em> paragraph.</a>" \
  catchline="alephDAM by 200ok GmbH" \
  seo-title="This is a SEO title" \
  seo-description="This is a SEO description." \
  locations:='[{"type": "city", "value": "Zürich"}]' \
  paywall-state="metered" \
  teaser="a modular Digital Asset Managment System and Streaming Platform"

Let's create another document. This time it should resemble a video. It optionally takes misc metadata. The absolute minimum to ingest a new video is this:

• source_url: HTTP accessible URL from where alephDAM can download an asset.
• type: Everything ingested in alephDAM is a 'document'. In the case of creating a video document, the type would be "video".
• identifiers: The 'identifiers' from the upstream document. The type of these identifiers will vary across agencies, products and types. The first identifier will be used to identify documents and subsequent updates of the same document. It serves as a foreign key.
• title: The 'title' of the upstream document.

Setting a poster image is technically not necessary, but a common use case:

• images: A list of attached images for the video. The first one will be used as a poster image.

There are a lot more options for setting metadata. For ease of use, we'll be doing a minimal example here. For more information on the available metadata, please see the API documentation for your specified instances of alephDAM.

http --ignore-stdin --pretty format \
     "#{endpoint}/api/v1/${tenant}/documents?token=${auth_token}" \
     identifiers:='["some_key_123"]' \
     title="Demo Video with poster image" \
     type="video" \
     language="en" \
     images:='[{"url": "https://i.imgur.com/6yIcT7u.png"}]' \
     source-url="https://200ok.ch/alephdam_fixtures/1234/mars.mp4"

{
    "errors": {
	"images": [
	    {
		"caption": "disallowed-key",
		"credit": "disallowed-key"
	    }
	],
	"paywall-state": "disallowed-key",
	"seo-description": "disallowed-key",
	"seo-title": "disallowed-key"
    }
}

Here's what such a request would look like in Swagger:

Now you have created a document in alephDAM and received a response with minimal information to later make queries on any updates regarding the document.

The document will now be processed in the background. To make further inquiries on the document, you can make subsequent requests. For that, you can use the unique identifier of the document, the uuid.

Here's how to receive information on this document, including the video URL and ID on Brightcove:

http --ignore-stdin --pretty format \
     "${endpoint}/api/v1/${tenant}/documents/${document_uuid}?token=${auth_token}"

{
    "agency": "lsi",
    "asset-size": null,
    "author": null,
    "bc-backlink": "https://studio.brightcove.com/products/videocloud/media/videos/6305secret",
    "bc-id": "6305980805112",
    "catchline": null,
    "categories": null,
    "complete": true,
    "created-at": "2022-05-12T09:33:09.889Z",
    "errors": [],
    "exported": null,
    "genres": null,
    "id": 3496049,
    "identifiers": [
	"my_key_321"
    ],
    "images": [],
    "keywords": null,
    "language": "de",
    "li-backlink": null,
    "locale": "de",
    "locations": null,
    "product": null,
    "published-datetime": null,
    "ready": true,
    "source-url": "https://200ok.ch/alephdam_fixtures/1234/mars.mp4",
    "special-rules": null,
    "teaser": null,
    "text": "",
    "title": "Demo Video",
    "type": "video",
    "updated-at": "2022-05-12T09:33:12.180Z",
    "urgency": null,
    "urn": "urn:lsi:video:my_key_321",
    "uuid": "3b3e8307-4a0c-4871-88a1-631df09e5154",
    "version": null,
    "video-state": null,
    "workflow": "process.lsi.application.json"
}

Here's what such a request would look like in Swagger:

If there is any error on uploading the video to Brightcove, extensive information will be added to the error field. For example:

"errors": [
  {
    "type": "export-video-to-bc",
    "message": "Create video request failed",
    "cause": "Reference id urn:lsi:video:1234 is already in use."
  }
]

Lists all agencies configured for a given tenant. The elements consist of the following attributes:

• name: alephDAM name for the agency
• language: ISO 639-1 language code
• products: List of upstream product names (verbatim from the agency)
• document_types: List of different types of documents delivered by the agency for this name, language and products combination.

Here's how to receive this list:

http --ignore-stdin --pretty format \
     "${endpoint}/api/v1/${tenant}/agencies?token=${auth_token}"

[
    {
	"document_types": [
	    "article"
	],
	"language": "de",
	"name": "dpa",
	"products": [
	    "weblines.sportsline.boxen.news",
	    "weblines.sportsline.fubawm.deutschesteam.news",
	    "weblines.sportsline.wintersport.skinordisch.news",
	    "weblines.sportsline.radsport.news",
	    "bdt"
	]
    },
    {
	"document_types": [
	    "article"
	],
	"language": "it",
	"name": "sda",
	"products": [
	    "Servizio Valli italiani",
	    "Photo Service F",
	    "ANSA (Transit)",
	    "Basisdienst I",
	    "ats-Online I",
	    "Spezialdienst Wahlen/Abstimmungen"
	]
    },
    {
	"document_types": [
	    "video"
	],
	"language": "en",
	"name": "reuters",
	"products": [
	    "VID"
	]
    }
]

For brevity, the result above is an excerpt of an actual response.