News API

News API

The Staffbase API is available under the URI https://backend.staffbase.com/api/. For sending requests to the resources described here please add the desired resource to the end of this base path, e.g. the absolute URI for the /posts-resource will be https://backend.staffbase.com/api/posts.

If your app is hosted on our German infrastructure, please use https://de.staffbase.com/api/ as base URI for all requests.

All end points for our News API require authentication. To learn how authentication works with the Staffbase API please consider the authentication section.

/branches

A branch is a Staffbase instance an admin creates for her company.

/branches/{branchID}

GET

Requests meta information about the requested branch.

URI Parameters

branchID string  required The ID of the branch.

Responses

200 OK

Returns meta information about the requested branch.

Examples:

{
  "id": "5791e3ffd4c61f21c3df8b8d",
  "name": "Example Organization",
  "slug": "exampleorg"
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}

/branch

This is a shorthandle path for /branches/{branchID}, where the branchID is the one of the API token.

GET

Requests meta information about the API token’s branch.

Responses

200 OK

Returns meta information about the API token’s branch.

Examples:

{
  "id": "5791e3ffd4c61f21c3df8b8d",
  "name": "Example Organization",
  "slug": "exampleorg"
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}

/branch/channels

GET

Requests all channels that are managable for the API token. This could be even unpublished channels.

Query Parameters

query string A string that is used for searching in the title of the channels.
limit number  default: 100 The amount of items that should be returned.
offset number  default: 0 Define an offset for getting the items starting at this number.
sort string  default: priority_DESC_updated_DESC The sort parameter can sort the request regarding two parameters following this regex: ^\w_(ASC|DESC)_\w_(ASC|DESC)$

Responses

200 OK

Returns all channels that are managable for the API token.

Examples:

{
  "total": 2,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "id": "5791e3ffd4c61f21c3df8b92",
      "config": {
        "localization": {
          "de_DE": {
            "title": "Kickstart für Ihre Mitarbeiter-App"
          },
          "en_US": {
            "title": "Kickstart your Employee App"
          }
        }
      },
      "published": "2016-07-22T09:14:39.157Z",
      "created": "2016-07-22T09:14:39.157Z",
      "updated": "2016-12-02T09:31:39.775Z"
    },
    {
      "id": "5791e3ffd4c61f21c3df8b96",
      "config": {
        "localization": {
          "de_DE": {
            "title": "Kurzmeldungen"
          },
          "en_US": {
            "title": "Short news"
          }
        }
      },
      "published": "2016-07-22T09:14:39.182Z",
      "created": "2016-07-22T09:14:39.182Z",
      "updated": "2016-10-19T12:18:10.434Z"
    }
  ]
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}

/channels

GET

Requests all accessible channels for the current context.

Query Parameters

query string A string that is used for searching in the title of the channels.
limit number  default: 100 The amount of items that should be returned.
offset number  default: 0 Define an offset for getting the items starting at this number.
sort string  default: priority_DESC_updated_DESC The sort parameter can sort the request regarding two parameters following this regex: ^\w_(ASC|DESC)_\w_(ASC|DESC)$

Responses

200 OK

Returns all accessible channels for the current context.

Examples:

{
  "total": 2,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "id": "5791e3ffd4c61f21c3df8b92",
      "config": {
        "localization": {
          "de_DE": {
            "title": "Kickstart für Ihre Mitarbeiter-App"
          },
          "en_US": {
            "title": "Kickstart your Employee App"
          }
        }
      },
      "published": "2016-07-22T09:14:39.157Z",
      "created": "2016-07-22T09:14:39.157Z",
      "updated": "2016-12-02T09:31:39.775Z"
    },
    {
      "id": "5791e3ffd4c61f21c3df8b96",
      "config": {
        "localization": {
          "de_DE": {
            "title": "Kurzmeldungen"
          },
          "en_US": {
            "title": "Short news"
          }
        }
      },
      "published": "2016-07-22T09:14:39.182Z",
      "created": "2016-07-22T09:14:39.182Z",
      "updated": "2016-10-19T12:18:10.434Z"
    }
  ]
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}

/channels/{channelID}

GET

Requests meta information about the requested channel.

URI Parameters

channelID string  required The ID of the channel.

Responses

200 OK

Returns meta information about the requested channel.

Examples:

{
  "id": "5791e3ffd4c61f21c3df8b92",
  "config": {
    "localization": {
      "de_DE": {
        "title": "Kickstart für Ihre Mitarbeiter-App"
      },
      "en_US": {
        "title": "Kickstart your Employee App"
      }
    }
  },
  "published": "2016-07-22T09:14:39.157Z",
  "created": "2016-07-22T09:14:39.157Z",
  "updated": "2016-07-22T09:14:39.157Z"
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}

/channels/{channelID}/posts

GET

Requests a list of posts within the specified channel.

URI Parameters

channelID string  required The ID of the channel.

Query Parameters

limit number  default: 10 The amount of items that should be returned.
offset number  default: 0 Define an offset for getting the items starting at this number.
sort string  default: priority_DESC_publishedDate_DESC The sort parameter can sort the request regarding two parameters following this regex: ^\w_(ASC|DESC)_\w_(ASC|DESC)$

Responses

200 OK

Returns a list of posts within the specified channel.

Examples:

{
  "total": 2,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "5791e3ffd4c61f21c3df8b93",
      "channelID": "5791e3ffd4c61f21c3df8b92",
      "externalID": "your-unique-external-id",
      "contents": {
        "en_US": {
          "content": "<p>Here is HTML.</p>",
          "image": {
            "original": {
              "url": "/image/upload/android-girl.jpg",
              "width": 1900,
              "height": 1069,
              "size": 753886
            }
          },
          "teaser": "Teaser is text only.",
          "title": "The Title"
        },
        "de_DE": {
          "content": "<p>Hier steht HTML.</p>",
          "image": {
            "original": {
              "url": "/image/upload/v1457622855/temp/android-girl.jpg",
              "width": 1900,
              "height": 1069,
              "size": 753886
            }
          },
          "teaser": "Teaser ist nur normaler Text",
          "title": "Ein Titel"
        }
      },
      "published": "2016-07-22T09:14:39.171Z",
      "created": "2016-07-22T09:14:39.171Z",
      "updated": "2016-07-22T09:14:39.171Z"
    },
    {
      "id": "5791e3ffd4c61f21c3df8b94",
      "channelID": "5791e3ffd4c61f21c3df8b92",
      "externalID": "your-unique-external-id2",
      "contents": {
        "en_US": {
          "content": "<p>This is another post with a <strong>strong-tag</strong></p>",
          "image": {
            "original": {
              "url": "/image/upload/network-en.jpg",
              "width": 1900,
              "height": 1069,
              "size": 1026588
            }
          },
          "teaser": "Post with strong-tag",
          "title": "Strong-Tag"
        },
          "de_DE": {
            "content": "<p>Dies ist ein weiterer Post mit <strong>Strong-Tag</strong>.</p>",
            "image": {
              "original": {
                "url": "/image/upload/network-en.jpg",
                "width": 1900,
                "height": 1069,
                "size": 1026588
              }
            },
            "teaser": "Post mit Strong-Tag",
            "title": "Strong-Tag"
          }
      },
      "published": "2016-07-22T09:14:39.170Z",
      "created": "2016-07-22T09:14:39.170Z",
      "updated": "2016-07-22T09:14:39.170Z"
    }
  ]
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}

POST

Adds a new post to the specified channel.

URI Parameters

channelID string  required The ID of the channel.
Body

Content-type: application/json

Examples:

{
  "externalID": "your-unique-external-id",
  "contents": {
    "en_US": {
      "content": "<p>Content could be HTML.</p>",
      "image": "https://example.org/dumb.png",
      "teaser": "This teaser should be text only.",
      "title": "A tittle"
    }
  },
  "published": "2016-07-22T09:14:39.171Z"
}

Responses

201 Created

The post has been successfully created. The response contains the newly created post as JSON.

Examples:

{
  "id": "5791e3ffd4c61f21c3df8b93",
  "channelID": "5791e3ffd4c61f21c3df8b92",
  "externalID": "your-unique-external-id",
  "contents": {
    "en_US": {
      "content": "<p>Here is HTML.</p>",
      "image": {
        "original": {
          "url": "/image/upload/android-girl.jpg",
          "width": 1900,
          "height": 1069,
          "size": 753886
        }
      },
      "teaser": "Teaser is text only.",
      "title": "The Title"
    },
    "de_DE": {
      "content": "<p>Hier steht HTML.</p>",
      "image": {
        "original": {
          "url": "/image/upload/v1457622855/temp/android-girl.jpg",
          "width": 1900,
          "height": 1069,
          "size": 753886
        }
      },
      "teaser": "Teaser ist nur normaler Text",
      "title": "Ein Titel"
    }
  },
  "published": "2016-07-22T09:14:39.171Z",
  "created": "2016-07-22T09:14:39.171Z",
  "updated": "2016-07-22T09:14:39.171Z"
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
403 Forbidden

This may occur when the used token has not the required permissions to perform this action.

Examples:

{
  "identifier": 40308,
  "statusCode": 403,
  "message": "Access to branch 'null' is restricted.",
  "type": "AccessDeniedException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}

/posts

GET

Requests a list of posts that are accessible for the API token.

Query Parameters

query string A string that is used for searching in title as well as content of posts.
limit number  default: 10 The amount of items that should be returned.
offset number  default: 0 Define an offset for getting the items starting at this number.
sort string  default: priority_DESC_publishedDate_DESC The sort parameter can sort the request regarding two parameters following this regex: ^\w_(ASC|DESC)_\w_(ASC|DESC)$

Responses

200 OK

Returns a list of posts that are accessible for the API token.

Examples:

{
  "total": 2,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "5791e3ffd4c61f21c3df8b93",
      "channelID": "5791e3ffd4c61f21c3df8b92",
      "externalID": "your-unique-external-id",
      "contents": {
        "en_US": {
          "content": "<p>Here is HTML.</p>",
          "image": {
            "original": {
              "url": "/image/upload/android-girl.jpg",
              "width": 1900,
              "height": 1069,
              "size": 753886
            }
          },
          "teaser": "Teaser is text only.",
          "title": "The Title"
        },
        "de_DE": {
          "content": "<p>Hier steht HTML.</p>",
          "image": {
            "original": {
              "url": "/image/upload/v1457622855/temp/android-girl.jpg",
              "width": 1900,
              "height": 1069,
              "size": 753886
            }
          },
          "teaser": "Teaser ist nur normaler Text",
          "title": "Ein Titel"
        }
      },
      "published": "2016-07-22T09:14:39.171Z",
      "created": "2016-07-22T09:14:39.171Z",
      "updated": "2016-07-22T09:14:39.171Z"
    },
    {
      "id": "5791e3ffd4c61f21c3df8b94",
      "channelID": "5791e3ffd4c61f21c3df8b92",
      "externalID": "your-unique-external-id2",
      "contents": {
        "en_US": {
          "content": "<p>This is another post with a <strong>strong-tag</strong></p>",
          "image": {
            "original": {
              "url": "/image/upload/network-en.jpg",
              "width": 1900,
              "height": 1069,
              "size": 1026588
            }
          },
          "teaser": "Post with strong-tag",
          "title": "Strong-Tag"
        },
          "de_DE": {
            "content": "<p>Dies ist ein weiterer Post mit <strong>Strong-Tag</strong>.</p>",
            "image": {
              "original": {
                "url": "/image/upload/network-en.jpg",
                "width": 1900,
                "height": 1069,
                "size": 1026588
              }
            },
            "teaser": "Post mit Strong-Tag",
            "title": "Strong-Tag"
          }
      },
      "published": "2016-07-22T09:14:39.170Z",
      "created": "2016-07-22T09:14:39.170Z",
      "updated": "2016-07-22T09:14:39.170Z"
    }
  ]
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}

/posts/{postID}

GET

Requests the specified posts including a set of comments.

URI Parameters

postID string  required This could be either the post’s ID defined by the API or if set the post’s externalID.

Query Parameters

commentsLimit integer  default: 10 The amount of comments that should be included.
commentsOffset integer  default: 0 Define an offset for getting the comments starting at this number.

Responses

200 OK

Returns the specified posts including a set of comments.

Examples:

{
  "id": "5791e3ffd4c61f21c3df8b93",
  "channelID": "5791e3ffd4c61f21c3df8b92",
  "externalID": "your-unique-external-id",
  "contents": {
    "en_US": {
      "content": "<p>Here is HTML.</p>",
      "image": {
        "original": {
          "url": "/image/upload/android-girl.jpg",
          "width": 1900,
          "height": 1069,
          "size": 753886
        }
      },
      "teaser": "Teaser is text only.",
      "title": "The Title"
    },
    "de_DE": {
      "content": "<p>Hier steht HTML.</p>",
      "image": {
        "original": {
          "url": "/image/upload/v1457622855/temp/android-girl.jpg",
          "width": 1900,
          "height": 1069,
          "size": 753886
        }
      },
      "teaser": "Teaser ist nur normaler Text",
      "title": "Ein Titel"
    }
  },
  "published": "2016-07-22T09:14:39.171Z",
  "created": "2016-07-22T09:14:39.171Z",
  "updated": "2016-07-22T09:14:39.171Z"
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
403 Forbidden

This may occur when the used token has not the required permissions to perform this action.

Examples:

{
  "identifier": 40308,
  "statusCode": 403,
  "message": "Access to branch 'null' is restricted.",
  "type": "AccessDeniedException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}

PUT

Updates a post by an incremental update.

URI Parameters

postID string  required This could be either the post’s ID defined by the API or if set the post’s externalID.
Body

Content-type: application/json

Examples:

{
  "externalID": "your-unique-external-id",
  "contents": {
    "en_US": {
      "content": "<p>Content could be HTML.</p>",
      "image": "https://example.org/dumb.png",
      "teaser": "This teaser should be text only.",
      "title": "A tittle"
    }
  },
  "published": "2016-07-22T09:14:39.171Z"
}

Responses

200 OK

The post has been successfully updated. Returns the recently updated post.

Examples:

{
  "id": "5791e3ffd4c61f21c3df8b93",
  "channelID": "5791e3ffd4c61f21c3df8b92",
  "externalID": "your-unique-external-id",
  "contents": {
    "en_US": {
      "content": "<p>Here is HTML.</p>",
      "image": {
        "original": {
          "url": "/image/upload/android-girl.jpg",
          "width": 1900,
          "height": 1069,
          "size": 753886
        }
      },
      "teaser": "Teaser is text only.",
      "title": "The Title"
    },
    "de_DE": {
      "content": "<p>Hier steht HTML.</p>",
      "image": {
        "original": {
          "url": "/image/upload/v1457622855/temp/android-girl.jpg",
          "width": 1900,
          "height": 1069,
          "size": 753886
        }
      },
      "teaser": "Teaser ist nur normaler Text",
      "title": "Ein Titel"
    }
  },
  "published": "2016-07-22T09:14:39.171Z",
  "created": "2016-07-22T09:14:39.171Z",
  "updated": "2016-07-22T09:14:39.171Z"
}
401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
403 Forbidden

This may occur when the used token has not the required permissions to perform this action.

Examples:

{
  "identifier": 40308,
  "statusCode": 403,
  "message": "Access to branch 'null' is restricted.",
  "type": "AccessDeniedException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}

DELETE

Removes a post from the system.

URI Parameters

postID string  required This could be either the post’s ID defined by the API or if set the post’s externalID.

Responses

204 No Content

The post has been successfully removed from the system.

401 Unauthorized

This may occur when a valid token is missing.

Examples:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point requires authentication.",
  "type": "NotLoggedInException"
}
403 Forbidden

This may occur when the used token has not the required permissions to perform this action.

Examples:

{
  "identifier": 40308,
  "statusCode": 403,
  "message": "Access to branch 'null' is restricted.",
  "type": "AccessDeniedException"
}
404 Not found

This may occur when the requested resource does not exist.

Examples:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
  "type": "NotFoundException"
}