Beamer API

Beamer API (Beta) API Reference

These are the developer docs for the open beta of the Beamer API.

You can find your API key under Settings > API .

For more information on how to use Beamer in your site, check out our web Documentation. For any other doubts you may have about how Beamer works, check out our Help Center.

API Endpoint
https://api.getbeamer.com/v0
Contact: info@getbeamer.com
Schemes: https
Version: 0.1.0

Authentication

api_key

type
apiKey
in
header
name
Beamer-Api-Key

Posts

Operations on your Beamer posts

Create a new post

POST /posts

Use the POST method to create a new post on your account.

Send a JSON object in the body of the request containing the details of the post to create.

All the main content fields of the post (such as title and content) are arrays of strings, in order to allow the creation of several translations simultaneously.

If you are creating a post with several translations, keep the same order when completing all of the translation-specific fields ( title, content, language, link text, link URL and custom category).

The first translation will be created from the first language, the first title, the first content, the first link text, the first link URL and the first custom category (if any).

Likewise, the second translation will be created from the second title, the second content, and so on.

Request Content-Types: application/json
Request Example
{
  "title": [
    "Title of your post"
  ],
  "content": [
    "Content of your post"
  ],
  "category": "new",
  "customCategory": [
    "string"
  ],
  "publish": true,
  "linkUrl": [
    "https://www.getbeamer.com/"
  ],
  "linkText": [
    "https://www.getbeamer.com/"
  ],
  "date": "2018-12-31T00:00:00",
  "language": [
    "EN"
  ],
  "filter": "admins",
  "enableFeedback": true,
  "enableReactions": true,
  "autoOpen": true,
  "userEmail": "example@getbeamer.com"
}
201 Created

Post created.

The request returns a JSON object containing the details of the post.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "123",
  "date": "2018-12-31T00:00:00Z",
  "published": "true",
  "category": "new",
  "translations": [
    {
      "title": "Title of the post.",
      "content": "Content of the post.",
      "contentHtml": "<p>Content of the post.</p>",
      "language": "EN",
      "category": "Category",
      "linkUrl": "https://www.getbeamer.com/",
      "linkText": "Click here!",
      "images": [
        "https://app.getbeamer.com/pictures?id=123"
      ]
    }
  ],
  "filter": "admins",
  "autoOpen": "false",
  "editionDate": "2018-12-31T10:00:00Z",
  "feedbackEnabled": "true",
  "reactionsEnabled": "true"
}

Get existing posts

GET /posts

Use the GET method to query and retrieve existing posts from your account.

filter
in query
string

Retrieve posts with a matching segmentation filter.

date
in query
string

Retrieve posts published after this date. The date must follow the ISO-8601 format.

language
in query
string

Retrieve posts with translations in this language.

maxResults
in query
integer

Retrieve this many posts (at most). The hard maximum (and default number) of posts returned is 100.

page
in query
integer

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of posts.

published
in query
boolean

Retrieve only published or draft (not published) posts. If unspecified, both types of posts will be retrieved.

200 OK

Posts retrieved.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "123",
    "date": "2018-12-31T00:00:00Z",
    "published": "true",
    "category": "new",
    "translations": [
      {
        "title": "Title of the post.",
        "content": "Content of the post.",
        "contentHtml": "<p>Content of the post.</p>",
        "language": "EN",
        "category": "Category",
        "linkUrl": "https://www.getbeamer.com/",
        "linkText": "Click here!",
        "images": [
          "https://app.getbeamer.com/pictures?id=123"
        ]
      }
    ],
    "filter": "admins",
    "autoOpen": "false",
    "editionDate": "2018-12-31T10:00:00Z",
    "feedbackEnabled": "true",
    "reactionsEnabled": "true"
  }
]

Get post by ID

GET /posts/{postId}

Returns a post

postId
in path
integer (int64)

ID of the post to retrieve.

200 OK

Post retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/xml, application/json
Response Example (200 OK)
{
  "id": "123",
  "date": "2018-12-31T00:00:00Z",
  "published": "true",
  "category": "new",
  "translations": [
    {
      "title": "Title of the post.",
      "content": "Content of the post.",
      "contentHtml": "<p>Content of the post.</p>",
      "language": "EN",
      "category": "Category",
      "linkUrl": "https://www.getbeamer.com/",
      "linkText": "Click here!",
      "images": [
        "https://app.getbeamer.com/pictures?id=123"
      ]
    }
  ],
  "filter": "admins",
  "autoOpen": "false",
  "editionDate": "2018-12-31T10:00:00Z",
  "feedbackEnabled": "true",
  "reactionsEnabled": "true"
}

Update an existing post

PUT /posts/{postId}

Updates the post with the existing ID.

JSON object containing the details of the post to update.

postId
in path
integer (int64)

ID of the post to retrieve.

Request Content-Types: application/json
Request Example
{
  "title": [
    "Title of your post"
  ],
  "content": [
    "Content of your post"
  ],
  "category": "new",
  "customCategory": [
    "string"
  ],
  "publish": true,
  "linkUrl": [
    "https://www.getbeamer.com/"
  ],
  "linkText": [
    "https://www.getbeamer.com/"
  ],
  "date": "2018-12-31T00:00:00",
  "language": [
    "EN"
  ],
  "filter": "admins",
  "enableFeedback": true,
  "enableReactions": true,
  "autoOpen": true,
  "userEmail": "example@getbeamer.com"
}
200 OK

Post updated.

The request returns a JSON object containing the details of the post.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "123",
  "date": "2018-12-31T00:00:00Z",
  "published": "true",
  "category": "new",
  "translations": [
    {
      "title": "Title of the post.",
      "content": "Content of the post.",
      "contentHtml": "<p>Content of the post.</p>",
      "language": "EN",
      "category": "Category",
      "linkUrl": "https://www.getbeamer.com/",
      "linkText": "Click here!",
      "images": [
        "https://app.getbeamer.com/pictures?id=123"
      ]
    }
  ],
  "filter": "admins",
  "autoOpen": "false",
  "editionDate": "2018-12-31T10:00:00Z",
  "feedbackEnabled": "true",
  "reactionsEnabled": "true"
}

Deletes a post

DELETE /posts/{postId}

Deletes the post with the given ID.

postId
in path
integer (int64)

ID of the post to delete.

204 No Content

Post deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

500 Internal Server Error

Something went wrong on our side.

Ping

Ping the Beamer API

Ping the API

POST /ping

Use /ping to check you are correctly authenticating your requests with your API key.

200 OK

Request authenticated. The request returns a JSON object containing the name of your product on Beamer.

type
object
401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "name": "Beamer"
}

Schema Definitions

PostCreation: object

title: string[]

Title of the post.

string
content: string[]

Content of the post.

string
category: Category
customCategory: string[]

Custom category for this post (required only when using the category " other").

string
publish: boolean

Whether to publish this post or save it as a draft.

linkUrl: string[]

The URL where users will be redirected to if they click the header of the post or the link shown at the bottom of it.

string
linkText: string[]

The text shown in the link ("linkUrl") of this post.

string
date: string

Publication date for this post in ISO-8601 format.

language: string[]

Language of this translation.

string
filter: string

Segmentation filter (or filters) for this post.

enableFeedback: boolean

Whether to enable or disable user feedback for this post.

enableReactions: boolean

Whether to enable or disable user reactions for this post.

autoOpen: boolean

Enable this to automatically open Beamer's sidebar the first time the user gets this post.

userEmail: string

Email of the user in your account creating this post.

Example
{
  "title": [
    "Title of your post"
  ],
  "content": [
    "Content of your post"
  ],
  "category": "new",
  "customCategory": [
    "string"
  ],
  "publish": true,
  "linkUrl": [
    "https://www.getbeamer.com/"
  ],
  "linkText": [
    "https://www.getbeamer.com/"
  ],
  "date": "2018-12-31T00:00:00",
  "language": [
    "EN"
  ],
  "filter": "admins",
  "enableFeedback": true,
  "enableReactions": true,
  "autoOpen": true,
  "userEmail": "example@getbeamer.com"
}

Post: object

id: integer (int64)

Unique identifier of this post.

date: string

Publication date of this post in ISO-8601 format.

published: boolean

Whether this post is published or a draft.

category: Category
translations: Translation
Translation
filter: string

Segmentation filter for this post.

autoOpen: boolean

Whether this post automatically opens Beamer's sidebar the first time the user gets it.

editionDate: string

Date of the last edition made on this post in ISO-8601 format.

feedbackEnabled: boolean

Whether this user feedback is enabled for this post.

reactionsEnabled: boolean

Whether this user reactions are enabled for this post.

Example
{
  "id": "123",
  "date": "2018-12-31T00:00:00Z",
  "published": "true",
  "category": "new",
  "translations": [
    {
      "title": "Title of the post.",
      "content": "Content of the post.",
      "contentHtml": "<p>Content of the post.</p>",
      "language": "EN",
      "category": "Category",
      "linkUrl": "https://www.getbeamer.com/",
      "linkText": "Click here!",
      "images": [
        "https://app.getbeamer.com/pictures?id=123"
      ]
    }
  ],
  "filter": "admins",
  "autoOpen": "false",
  "editionDate": "2018-12-31T10:00:00Z",
  "feedbackEnabled": "true",
  "reactionsEnabled": "true"
}

Translation: object

title: string

Title of the post.

content: string

Content of the post (plain text).

contentHtml: string

Content of the post (original HTML format).

language: string

Language of this post.

category: string

Custom category of this post.

linkUrl: string

The URL where users will be redirected to if they click the header of the post or the link shown at the bottom of it.

linkText: string

The text shown in the link ("linkUrl") of this post.

images: string[]

URLs of the images embedded in this post.

string
Example
{
  "title": "Title of the post.",
  "content": "Content of the post.",
  "contentHtml": "<p>Content of the post.</p>",
  "language": "EN",
  "category": "Category",
  "linkUrl": "https://www.getbeamer.com/",
  "linkText": "Click here!",
  "images": [
    "https://app.getbeamer.com/pictures?id=123"
  ]
}

Category: string

Category of the post.

string new, improvement, fix, comingsoon, announcement, other