Post API

Post API

DIVE's Post API enables you to automate the publication process.

Table of Contents

Endpoints
Authentication method
API Token invalidation
Post object
Post object - fields
Images, Videos and PDFs - media files in the Post API
MediaUploadRequest object
MediaUploadRequest object - fields
Errors

Endpoints

Several endpoints make up the API—Click on an endpoint to get to its dedicated page:

• /add_post
• /get_post
• /get_posts
• /update_post
• /delete_post
• /add_media_upload_request
• /get_media_upload_request
• /get_content_zones

Notes

1. The Base URL for all endpoints is https://dive-networks.com/api/rpc/34.
2. All endpoints require an HTTP Auth Header: Authorization: Token your-api-token-here.
3. The API access is restricted to the following account types:
   • superuser,
   • author,
   • editor,
   • superauthor.

Authentication Method

DIVE's API authentication & authorization is based on JWT (JSON Web Tokens). For the API purposes we call them API Tokens.

This mechanism is fairly simple. The API Token may be obtained from the Settings page and passed as the token of the Authorization header (Authorization: Token your-api-token-here). Note that the value of the Authorization header starts with the Token keyword.

API Token Invalidation

If you suspect that your API Token was exposed, you should invalidate it immediately. To invalidate a token, visit the Settings page and select the Invalidate API Token option. That invalidates your API Token and generates a new one automatically.

To invalidate API Tokens of all of your employees, reach out to DIVE's support deportment.

Post object

The Post object is composed of many fields. The field types fall into three categories: always required, conditionally required, and optional. Most of the conditionally required fields depend on the template field's value which indicates type of the post.

Fields:

Field	Required?	Default	Description
"id"	No	-	Post's identifier.
"template"	Yes	-	Post's type. Many of the conditionally required fields depend on the value of this field.
"is_published"	No	true	Indicates whether the post is published.
"title"	Yes	-	Title of the post.
"subtitle"	No	null	Subtitle of the post.
"body"	Conditionally	null	Textual content of the post.
"text_color"	No	"000000"	Text color.
"background_color"	No	"ffffff"	Background color.
"intro_text_color"	No	"ffffff"	Intro text color.
"intro_background_color"	No	"6d4fc3"	Intro background color.
"image_url"	Conditionally	null	Image URL.
"image_height"	Conditionally	null	Image height.
"image_width"	Conditionally	null	Image width.
"uploaded_file_s3_key"	Conditionally	""	S3 key of the file (e.g. image) uploaded through the API.
"uploaded_file_s3_bucket"	Conditionally	""	S3 bucket of the file (e.g. video) uploaded through the API.
"uploaded_file_size_bytes"	Conditionally	null	Size of the file (e.g. pdf) uploaded through the API.
"iframe_url"	Conditionally	null	Embedded web page (iframe) URL.
"pdf_url"	Conditionally	null	PDF URL.
"pdf_thumbnail_url"	Conditionally	null	PDF thumbnail URL.
"pdf_height"	Conditionally	null	PDF height.
"pdf_width"	Conditionally	null	PDF width.
"pdf_numpages"	Conditionally	null	Number of pages of uploaded PDF.
"youtube_url"	Conditionally	null	URL of a YouTube video.
"video_url"	Conditionally	null	Video URL.
"video_filename"	Conditionally	null	Video filename.
"media_type"	No	null	Type of media (e.g. image or video url) associated with the post.
"show_text_in_ticker"	No	false	Indicates whether to show text from this post in the ticker.
"show_post_in_player_window"	No	true	Indicates whether to show this post in the player's window.
"show_data_source_in_player"	No	true	Indicates whether to show data source in the player's window.
"fullscreen_playback"	No	false	Indicates whether to hide ticker and title bar during content playback.
"show_title_in_player"	No	true	Indicates whether to show (include) title when displaying post.
"show_publication_time"	No	false	Indicates whether to show when post was published (e.g. 2 hours ago).
"text_layout"	No	"auto"	Text layout (e.g. automatic, top, middle or bottom).
"image_layout"	No	"auto"	Image layout (e.g. automatic or completely cover blank space with image).
"content_zones"	Conditionally	[]	Content zones (locations) in which the post will be displayed.
"schedule_start"	No	now	Indicates when to start displaying of the post.
"schedule_end"	No	now + 7 days	Indicates when to end up displaying of the post.
"frequency"	No	300	Indicates how often (roughly) to play the post.
"priority"	No	"low"	Indicates the priority of the post. Higher priority posts come first when several posts are due to play around the same time.
"duration"	No	null	Duration of the post (in seconds).
"override_start"	Conditionally	null	Indicates when to start overriding.
"override_end"	Conditionally	null	Indicates when to end up overriding.

"id":

• Type: int
• Value is assigned automatically

"template":

• Type: string
• Choices:
  • "text"
  • "text+image"
  • "image"
  • "iframe"
  • "pdf"
  • "video"
  • "video-upload"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"is_published":

• Type: bool
• Default: true
• Possible values: true/false
• Applies to all "template"s

"title":

• Type: string
• Max length: 200
• Applies to all "template"s

"subtitle":

• Type: null/string
• Default: null
• Max length: 200
• Only applies to the following "template"s:
  • "text"
  • "text+image"
  • "pdf"
  • "new-employee"
  • "employee-recognition"
  • "brithday-greeting"
  • "welcome-guest"
  • "content-list"

"body":

• Type: null/string
• Default: null
• Max length: 2500
• Required for the following "template"s:
  • "text"
  • "text+image"
  • "content-list"
• Only applies to the following "template"s:
  • "text"
  • "text+image"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"text_color":

• Type: null/string
• Default: null or "000000" for the "template"s for which the field applies (listed below)
• Exact length: 6
• Allowed characters: [0-9a-fA-F]
• Only applies to the following "template"s:
  • "text"
  • "text+image"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"background_color":

• Type: string
• Default: "ffffff"
• Exact length: 6
• Allowed characters: [0-9a-fA-F]
• Applies to all "template"s

"intro_text_color":

• Type: null/string
• Default: null or "ffffff" for the "template"s for which the field applies (listed below)
• Exact length: 6
• Allowed characters: [0-9a-fA-F]
• Only applies to the following "template"s:
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"intro_background_color":

• Type: null/string
• Default: null or "6d4fc3" for the "template"s for which the field applies (listed below)
• Exact length: 6
• Allowed characters: [0-9a-fA-F]
• Only applies to the following "template"s:
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"image_url":

• Type: null/url
• Default: null
• Max length: 1000
• Required for the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
• Required for the following "template"s if "media_type" is set to "image":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"image_height":

• Type: null/int
• Default: null
• Min value: 0
• Required for the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
• Required for the following "template"s if "media_type" is set to "image":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"image_width":

• Type: null/int
• Default: null
• Min value: 0
• Required for the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
• Required for the following "template"s if "media_type" is set to "image":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"uploaded_file_s3_key":

• Type: string
• Default: ""
• Max length: 255
• Required for the following "template"s:
  • "text+image"
  • "image"
  • "video-upload"
• Required for the following "template"s if "media_type" is set to "image":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "video-upload"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"uploaded_file_s3_bucket":

• Type: string
• Default: ""
• Max length: 255
• Required for the following "template"s:
  • "text+image"
  • "image"
  • "video-upload"
• Required for the following "template"s if "media_type" is set to "image":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "video-upload"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"uploaded_file_size_bytes":

• Type: null/int
• Default: null
• Min value: 0
• Required for the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
  • "video-upload"
• Required for the following "template"s if "media_type" is set to "image":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
  • "video-upload"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"iframe_url":

• Type: null/url
• Default: null
• Max length: 1000
• Required for the "iframe" "template"
• Only applies to the "iframe" "template"

"pdf_url":

• Type: null/url
• Default: null
• Max length: 1000
• Required for the "pdf" "template"
• Only applies to the "pdf" "template"

"pdf_thumbnail_url":

• Type: null/url
• Default: null
• Max length: 1000
• Required for the "pdf" "template"
• Only applies to the "pdf" "template"

"pdf_height":

• Type: null/int
• Default: null
• Min value: 0
• Required for the "pdf" "template"
• Only applies to the "pdf" "template"

"pdf_width":

• Type: null/int
• Default: null
• Min value: 0
• Required for the "pdf" "template"
• Only applies to the "pdf" "template"

"pdf_numpages":

• Type: null/int
• Default: null
• Min value: 0
• Required for the "pdf" "template"
• Only applies to the "pdf" "template"

"youtube_url":

• Type: null/url
• Default: null
• Max length: 300
• Required for the "video" "template"
• Required for the following "template"s if "media_type" is set to "youtube-video":
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
• Only applies to the following "template"s:
  • "video"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"video_url":

• Type: null/url
• Default: null
• Max length: 1000
• Required for the following "template": "video-upload"
• Only applies to the "video-upload" "template"

"video_filename":

• Type: null/string
• Default: null
• Max length: 300
• Required for the following "template": "video-upload"
• Only applies to the "video-upload" "template"

"media_type":

• Type: null/string
• Default: null
• Choices:
  • null
  • "youtube-video"
  • "image"
• Only applies to the following "template"s:
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"show_text_in_ticker":

• Type: bool
• Default: false
• One of the following fields must be true:
  • "show_text_in_ticker"
  • "show_post_in_player_window"
• Only applies to the following "template"s:
  • "text"
  • "text+image"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"show_post_in_player_window":

• Type: bool
• Default: true
• One of the following fields must be true:
  • "show_text_in_ticker"
  • "show_post_in_player_window"
• Only applies to the following "template"s:
  • "text"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"
  • "content-list"

"show_data_source_in_player":

• Type: bool
• Default: true
• Applies to all "template"s

"fullscreen_playback":

• Type: bool
• Default: false
• Applies to all "template"s

"show_title_in_player":

• Type: bool
• Default: true
• Applies to all "template"s

"show_publication_time":

• Type: bool
• Default: false
• Applies to all "template"s

"text_layout":

• Type: string
• Default: "auto"
• Choices:
  • "auto"
  • "top"
  • "middle"
  • "bottom"
• Only applies to the following "template"s:
  • "text"
  • "text+image"
  • "pdf"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"image_layout":

• Type: string
• Default: "auto"
• Choices:
  • "auto"
  • "contain"
  • "scale-down"
  • "cover"
• Only applies to the following "template"s:
  • "text+image"
  • "image"
  • "pdf"
  • "new-employee"
  • "employee-recognition"
  • "birthday-greeting"
  • "welcome-guest"
  • "company-news"

"content_zones":

• Type: array of ints
• Default: []
• Required if "is_published" field is true (you must provide at least one content zone when publishing a post)
• Applies to all "template"s

"schedule_start":

• Type: datetime (iso-8601 format)
• Default: now
• Cannot be greater than or equal to "schedule_end"
• Applies to all "template"s

"schedule_end":

• Type: datetime (iso-8601 format)
• Default: now + 7 days
• Must be greater than "schedule_start"
• Applies to all "template"s

"frequency":

• Type: integer
• Default: 300 (every 5 minutes)
• Choices:
  • 120 (Every 2 minutes)
  • 180 (Every 3 minutes)
  • 240 (Every 4 minutes)
  • 300 (Every 5 minutes (default))
  • 360 (Every 6 minutes)
  • 420 (Every 7 minutes)
  • 480 (Every 8 minutes)
  • 540 (Every 9 minutes)
  • 600 (Every 10 minutes)
  • 900 (Every 15 minutes)
  • 900 (Every 20 minutes)
  • 1800 (Every 30 minutes)
  • 3600 (Every hour)
  • 7200 (Every 2 hours)
  • 10800 (Every 3 hours)
  • 14400 (Every 4 hours)
  • 86400 (Once a day)
• Applies to all "template"s

"priority":

• Type: string
• Default: "low"
• Choices:
  • "low"
  • "medium"
  • "high"
• Applies to all "template"s

"duration":

• Type: null/int
• Default: null
• Min value: 5
• Max value: 120
• Applies to all "template"s

"override_start":

• Type: null/datetime (iso-8601 format)
• Default: null
• Cannot be greater than or equal to "override_end"
• Required if "override_end" is not null
• Applies to all "template"s

"override_end":

• Type: null/datetime (iso-8601 format)
• Default: null
• Must be greater than "override_start"
• Required if "override_start" is not null
• Applies to all "template"s

Images, Videos and PDFs - media files in the Post API

The Post object has media-related fields. However, to fill some of these fields and to associate a Post with a media file we recommend to upload the file to our S3 bucket through a MediaUploadRequest object. Our serverless system behind the S3 bucket will process the file and save its metadata to the MediaUploadRequest object.

How does it work? Let's see an example with an image. Consider following along via the Python shell before proceeding with the implementation.

Note that proper error handling is not included in this example for the sake of brevity.

import requests


# 1. Create `MediaUploadRequest` object:
response = requests.post(
    'https://dive-networks.com/api/rpc/34/add_media_upload_request',
    headers={'Authorization': 'Token your-api-token-here'},
    json={'media_type': 'image'}
)
media_upload_request = response.json().get['result']

# 2. Upload your media file using the `"presigned_s3_post"` data returned
#    by `/add_media_upload_request` request:
# Note: The `"presigned_s3_post"` is valid for 10 minutes only.
#  If that time elapses, just create a new one.
requests.post(
    media_upload_request['presigned_s3_post']['url'],
    data=media_upload_request['presigned_s3_post']['fields'],
    files={'file': open('C:\\Users\\domin\\Pictures\\image.JPG', 'rb')}
)

# Our serverless system behind the S3 bucket will process the file.
# It will update the `MediaUploadRequest` object with the file metadata after processing.

# 3. Poll the `MediaUploadRequest` object for the file metadata:
# Note: At this point the `"status"` of `MediaUploadRequest` object should
#  be equal to `"init"` or `"processing"`.
#  You may need to send `/get_media_upload_request` several times until
#  the serverless system finish processing and update the `MediaUploadRequest`
#  object. The timeout of processing is 15 minutes, so we recommend to send
#  the `/get_media_upload_request` request every N (e.g. 10) seconds until
#  the `"status"` of `MediaUploadRequest` object is `"succeeded"` or
#  `"failed"`. If it is `"succeeded"` then it should contain the file metadata
#  under the `"data"` key. Otherwise, if it is `"failed"` you should try to
#  upload the file again or contact the DIVE' staff to solve the issue.)
response = requests.post(
    'https://dive-networks.com/api/rpc/34/get_media_upload_request',
    headers={'Authorization': 'Token your-api-token-here'},
    json={'id': media_upload_request['id']}
)
image_data = response.json()['result']['data']

# 4. Use the file metadata to add (or update) a `Post`:
requests.post(
    'https://dive-networks.com/api/rpc/34/add_post',
    headers={'Authorization': 'Token your-api-token-here'},
    json={
        'template': 'image',
        'is_published': False,
        'title': 'Post with an image',
        **image_data    # Unpack the image data.
    }
)

MediaUploadRequest object

A MediaUploadRequest object is required to upload a file to our S3 bucket. It generates a presigned S3 URL and a form data to make it possible. It also stores file metadata if the processing behind the bucket was successful.

Fields:

Field	Description
"id"	MediaUploadRequest's identifier.
"status"	MediaUploadRequest's status.
"media_type"	Type of the media file you want to upload.
"presigned_s3_post"	Presigned S3 URL & form data with permissions to upload to our S3 bucket.
"data"	Media file's metadata gathered after uploading & processing.
"expires_at"	The expiration timestamp of the presigned s3 post data.
"created_at"	The creation timestamp of the MediaUploadRequest object.
"updated_at"	The update timestamp of the MediaUploadRequest object.

"id":

• Type: int
• Value is assigned automatically

"status":

• Type: string
• Readonly
• Possible values:
  • "init"
  • "processing"
  • "succeeded"
  • "failed"

"media_type":

• Type: string
• Choices:
  • "image"
  • "video"
  • "pdf"

"presigned_s3_post":

• Type: object
• Readonly
• Contains:
  • "url":
    • Type: string
    • It is a presigned S3 URL
  • "fields":
    • Type: object
    • Contains presigned S3 form data

"data":

• Type: object
• Readonly
• If "status" is "succeeded" it should contain the uploaded file's metadata that should be used for adding/updating a Post (you need to unpack this object just like the example on the above section)

"expires_at":

• Type: datetime (iso-8601 format)
• Default: now + 10 minutes
• Readonly

"created_at":

• Type: datetime (iso-8601 format)
• Default: now
• Readonly

"updated_at":

• Type: datetime (iso-8601 format)
• Its value is set to now during each update
• Readonly

Errors

Most of errors you may receive from the API are self-descriptive, therefore we only provide a general description.

400 Bad Request - This error occurs if the body of your request is not valid. Please, make sure that it is valid and the HTTP method is POST. Usually, this error is accompanied by a self-descriptive message.

403 Forbidden - You are not authorized. Please, check your API Token or make sure that you have required permissions set.

404 Not Found - This error occurs if the URL you are requesting does not exist or the object the request refers to does not exist. Please, make sure that the URL or the object ID you are requesting is valid.

405 Method Not Allowed - This error occurs if the endpoint you are requesting does not support the HTTP Method used for the request. Please, make sure that the HTTP Method you use is supported by the endpoint.