Place

Place Service

Web service endpoints for functionality that is common to all places. The standard place types (and corresponding entities) are:

  • blog (Blog) - a blog, associated with this place, in which people can create posts related to activity that is coordinated in this place.
  • group (Group) - a social group, with defined members, typically focused on a particular topic.
  • project (Project) - a project (with associated tasks) to track progress towards particular goals.
  • space (Space) - a formally defined (typically around departmental or topical hierarchies) location for communication about a particular topic.

See Place Use Cases for usage examples.

Create Content

POST /places/{placeID}/contents

Create a new content object with specified characteristics, and return an entity representing the newly created content object.

For those types of content that support attachments, it is possible to specify URL of files that the server will download and store them as attachments of the new content. A BAD_REQUEST error will be returned if URL of files are passed and the content type does not support attachments. Here we can see an example where attachments are specified as URLs.

  {
    "content":{
       "type":"text/html",
       "text":"<body><p>Some interesting text</p></body>"
    },
    "subject":"New Document",
    "type":"document",
    "attachments":[
       {
          "doUpload":true,
          "url":"http://www.mysite.com/images/cat.jpg"
       }
    ]
 }

Attachments can only be images when creating Update. Those images will be accessible through the images resource of an Update.

The following rules define which fields in the incoming JSON entity are processed:

  • For all content object types, the following fields are processed: author, content, parent, status, subject, tags, type.
  • For all content object types, the content and subject fields are required. Furthermore, subject must be unique within the parent place.
Query Parameters:
NameTypeRequiredDescription
publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content. Since 3.6.
updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content. Since 3.6.
fieldsStringfalseThe fields to include in the returned entity
Takes:
  • A Content describing the content object to be created
    • Retrieves:
  • Content representing the newly created content
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two contents of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified content

    Upload New Content

    POST /places/{placeID}/contents

    Create a new content object with specified characteristics, and return an entity representing the newly created content object. Uploaded files will be added to the new content object as attachments. Uploading attachments is only allowed for those content types that support attachments. A BAD_REQUEST error will be returned if attachments are passed and the content type does not support them.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all content object types, the following fields are processed: author, content, parent, status, subject, tags, type.
    • For all content object types, the author, content, parent, and subject fields are required, and must be unique within the parent place.
    Query Parameters:
    NameTypeRequiredDescription
    publishedStringfalseDate and time when this content object was originally created. Set 'updated' param as well. Only set this field when importing content. Since 3.6.
    updatedStringfalseDate and time when this content object was most recently updated. Set 'published' param as well. Only set this field when importing content. Since 3.6.
    fieldsStringfalseThe fields to include in the returned entity
    Takes:
  • A multipart of subtype form-data that will include a section with a Content describing the content to be created and another section for each file being uploaded.
    • Retrieves:
  • Content representing the newly created content
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two contents of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified content

    Create Ext Props

    POST /places/{placeID}/extprops

    Save a new set of extended properties for a place with specified characteristics, and return an entity representing the newly created extended properties.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being created on the target place will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create a extended properties
    Takes:
  • ExtProps describing the extended properties to be saved
    • Retrieves:
  • ExtProps representing the newly created extended property
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage extended properties for the place

    Create Ext Props For Addon

    POST /places/{placeID}/extprops/addOn/{addonUUID}

    For the specified addon, save a new set of extended properties for a place with specified characteristics, and return an entity representing the newly created extended properties.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create a extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are created.
    Takes:
  • ExtProps describing the extended properties to be saved
    • Retrieves:
  • ExtProps representing the newly created extended property
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage extended properties for the place
    Since: 3.9

    Create Place

    POST /places

    Create a new place with specified characteristics, and return an entity representing the newly created place.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all place types, the following fields are processed: contentTypes, description, displayName, name, parent, tags.
    • For all place types, the displayName and name fields are required, and must be unique within the parent place.
    • If the parent field is not included, the root space will be the default parent of the new place.
    Query Parameters:
    NameTypeRequiredDescription
    publishedStringfalseDate and time when this place was originally created. Set 'updated' param as well. Only set this field when importing content. Since 3.6.
    updatedStringfalseDate and time when this place was most recently updated. Set 'published' param as well. Only set this field when importing content. Since 3.6.
    fieldsStringfalseFields to include in the returned entity
    Takes:
  • Place describing the place to be created
    • Retrieves:
  • Place representing the newly created place
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two places of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified place

    Create Place Announcement

    POST /places/{placeID}/announcements

    Create a new announcement associated with this place. An appropriate parent field will be calculated and injected automatically.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create an announcement
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned Announcement
    Takes:
  • Announcement describing the announcement to be created
    • Retrieves:
  • Announcement representing the newly created announcement
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to create announcements in the specified place
    404 (Not Found)The specified parent place cannot be found

    Create Place Avatar

    POST /places/{placeID}/avatar

    Register a new avatar image (or replace an existing one) from the specified URI. The image will be downloaded and scaled as necessary. Note that avatar images are not supported on blogs.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create or replace an avatar image
    Query Parameters:
    NameTypeRequiredDescription
    uriStringfalseURI of a JPG, PNG, or GIF formatted image
    Retrieves:
  • An HTTP 201 (Created) status if the image was created, or 204 (No Content) if an existing image was replaced
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful, and a new image was uploaded
    204 (No Content)Request was successful, and an existing image was replaced
    400 (Bad Request)The specified URI is malformed
    409 (Conflict)This place type does not support avatar images
    404 (Not Found)The specified place or image does not exist

    Create Place Category

    POST /places/{placeID}/categories

    Create a new category for a place with specified characteristics, and return an entity representing the newly created category.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create a category
    Query Parameters:
    NameTypeRequiredDescription
    autoCategorizeStringfalseFlag indicating whether existing content of the place will be categorized under the new category
    fieldsStringfalseFields to be returned (default is @all)
    Takes:
  • Category describing the category to be created
    • Retrieves:
  • Category representing the newly created category
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed or max number of categories has been reached
    409 (Conflict)The new entity would conflict with system restrictions (such as two categories with the same name)
    403 (Forbidden)You are not allowed to manage categories for the place

    Create Place Static with Data

    POST /places/{placeID}/statics

    Create and return a new static resource associated with the specified place. The minimum information needed is:

         {
         "filename" : "{the filename of this resource}"
     }
    Takes:
    • Static with at least a "filename" field
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Takes:
  • Static describing the static resource to be created
    • Retrieves:
  • Static describing the new static resource
    • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)Input field is missing or malformed
    409 (Conflict)Attempt to add a second resource with the same filename
    201 (Created)Request was successful
    403 (Forbidden)You are not allowed to manage static resources for this place
    404 (Not Found)Specified place was not found

    Upload New Place Static Data

    POST /places/{placeID}/statics

    Create and return a new static resource associated with the specified place, including the specified data content. The minimum information needed in the JSON object is:

         {
         "filename" : "{the filename of this resource}"
     }
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Takes:
  • A multipart of subtype form-data that will include a section with a JSON object describing the static resource to be created, and another section containing the content of the static resource
    • Retrieves:
  • Static describing the new static resource
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)Input field is missing or malformed
    409 (Conflict)Attempt to add a second resource with the same filename
    403 (Forbidden)You are not allowed to manage static resources for this place
    404 (Not Found)Specified place was not found

    Create Place Task

    POST /places/{placeID}/tasks

    Create a Task in a project.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the project for which to create a task
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned Task
    Takes:
  • Task containing information describing the new project task
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)Any of the input fields are malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two contents of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified content
    Since: 3.1

    Destroy Ext Props

    DELETE /places/{placeID}/extprops

    Delete the existing extended properties for the specified place.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted from the target place will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which the extended properties are to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties
    404 (Not Found)The specified place does not exist

    Destroy Ext Props For Addon

    DELETE /places/{placeID}/extprops/addOn/{addonUUID}

    For the specified add-on, delete the existing extended properties for the specified place.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which the extended properties are to be deleted
    addonUUIDStringtrueUUID of the addon for which the properties are to be deleted.
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties
    404 (Not Found)The specified place does not exist
    Since: 3.9

    Destroy Place

    DELETE /places/{placeID}

    Delete the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified place
    404 (Not Found)The specified place does not exist

    Destroy Place Avatar

    DELETE /places/{placeID}/avatar

    Delete the existing avatar image for the specified place. Note that avatar images are not supported on blogs.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which the avatar image is to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Destroy Place Category

    DELETE /places/{placeID}/categories/{categoryID}

    Delete the existing category for the specified place. Only admins of the place can manage place categories.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which the category is to be deleted
    categoryIDStringtrueID of the category to delete
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Get Activity

    GET /places/{placeID}/activities

    Return the activity stream for the specified place.

    The returned list will be empty if the place is private and the authenticated user is not a member.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to return activities
    Query Parameters:
    NameTypeRequiredDescription
    afterStringfalseDate and time representing the minimum "last activity in a collection" timestamp for selecting activities (cannot specify both after and before)
    beforeStringfalseDate and time representing the maxium "last activity in a collection" timestamp for selecting activities (cannot specify both after and before)
    countIntegerfalseMaximum number of activities to return in this request (you may get more activities than this in order to get all of the activities in the last collection)
    filterObject[]falseFilter expression(s) used to select matching results
    fieldsStringfalseFields to be included in the returned activities
    collapseBooleanfalseWhether collapse the results such that there is only one entry per jive object
    oldestUnreadBooleanfalseEffective only when "collapse" is true. When this flag is set to true, service includes oldest unread item in collapsed list
    Retrieves:
  • Activity[] listing the requested activities
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)The specified place ID is missing or malformed
    403 (Forbidden)The requesting user is not allowed to retrieve activities for the specified place
    404 (Not Found)The activities or the specified user is not found

    Get Applied Entitlements

    GET /places/{placeID}/appliedEntitlements

    Obtains a paginated list of applied entitlement entities for a given place id

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to resolve entitlements
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index at which to start results
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be included in the returned entities
    Retrieves:
  • AppliedEntitlement[] listing the applied entitlements
    • Return Status:
    HTTP Status CodeDescription
    403 (Forbidden)if the requesting user is not authorized to view applied entitlements
    303 (See Other)if the requested space is inheriting permissions from another space
    Since: 3.8

    Get Content

    GET /places/{placeID}/contents

    Return a list of featured content objects in the specified place.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    type one or more object types of desired contained content objects (document, discussion, post, poll) separated by commas ?filter=type(document,discussion)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this content object was created, in ascending order
    dateCreatedDesc Sort by the date this content object was created, in descending order. Default if none was specified.
    latestActivityAsc Sort by the date this content object had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this content object had the most recent activity, in descending order
    titleAsc Sort by content object subject, in ascending order

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    The returned list will be empty if the place is private and the authenticated user is not a member.

    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to be returned on each content
    sortStringfalseThe requested sort order
    startIndexIntegerfalseThe zero-relative index of the first matching content to be returned
    countIntegerfalseThe maximum number of contents to be returned
    fieldsStringfalseThe fields to be returned on each content
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    403 (Forbidden)You are not allowed to access the specified content object
    Since: 3.2

    Get Ext Props

    GET /places/{placeID}/extprops

    Return the specified extended properties of a place.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being fetched from the target place will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place that is associated to the extended properties
    Retrieves:
  • ExtProps containing the specified extended properties
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    404 (Not Found)If the specified place does not exist

    Get Ext Props For Add On

    GET /places/{placeID}/extprops/addOn/{addonUUID}

    For the specified add-on, return the specified extended properties of a place.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place that is associated to the extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are to be fetched.
    Retrieves:
  • ExtProps containing the specified extended properties
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    404 (Not Found)If the specified place does not exist
    Since: 3.9

    Get Featured Content

    GET /places/{placeID}/contents/featured

    Return a list of featured content objects in the specified place.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    type one or more object types of desired contained content objects (document, discussion, post, poll) separated by commas ?filter=type(document,discussion)

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to be returned on each content
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    403 (Forbidden)You are not allowed to access the specified content object
    Since: 3.2

    Get Pages

    GET /places/{placeID}/pages

    Return a list of pages related to the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to return pages
    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseFilter criteria used to select pages
    fieldsStringfalseFields to be included in returned pages
    Retrieves:
  • Page[]
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the requested pages

    Get Place

    GET /places/{placeID}

    Return the specified place with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned
    Retrieves:
  • Place
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified place
    404 (Not Found)The specified place does not exist

    Get Place Announcements

    GET /places/{placeID}/announcements

    Return a paginated list of announcements related to the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to return announcements
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first announcement to be returned
    countIntegerfalseMaximum number of announcements to be returned
    activeOnlyBooleanfalseTrue if only active (non-expired) announcements should be returned
    fieldsStringfalseFields to be included in returned announcements
    Retrieves:
  • Announcement[]
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the requested announcements

    Get Place Avatar

    GET /places/{placeID}/avatar

    Return the binary content of the avatar image for the specified place. Note that avatar images are not supported on blogs.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to retrieve the avatar image
    Query Parameters:
    NameTypeRequiredDescription
    sizeStringfalseRequested size ("small", "medium", "large"),default is "large"
    Retrieves:
  • The binary content of the avatar image for the specified place
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve this image
    404 (Not Found)The specified place or image does not exist

    Get Place Categories

    GET /places/{placeID}/categories

    Return categories associated to the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to return its categories
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned (default is @all)
    Retrieves:
  • Category[]

    • Get Place Category

    GET /places/{placeID}/categories/{categoryID}

    Return the specified category of a place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place that is associated to the category
    categoryIDStringtrueID of the category to return
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned (default is @all)
    Retrieves:
  • Category containing the specified category
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    404 (Not Found)If the specified category does not exist

    Get Place Followers

    GET /places/{placeID}/followers

    Return a paginated list of Persons about people who are following the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to check for followers
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first instance to be returned
    countIntegerfalseMaximum number of instances to be returned (i.e. the page size)
    fieldsStringfalseFields to be returned (or null for summary fields)
    Retrieves:
  • Person listing people following the specified place
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)The request criteria are malformed
    403 (Forbidden)The requesting user is not authorize to retrieve this user information
    404 (Not Found)The specified user cannot be found
    Since: 3.5

    Get Place Following In

    GET /places/{placeID}/followingIn

    Return the list of custom streams in which the requesting user is following this place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to check for following
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be included in the returned representation
    Retrieves:
  • Stream[] in which the requesting user is following this place
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this place
    404 (Not Found)The specified place does not exist

    Get Place Permissions

    GET /places/{placeID}/permissions

    Return the list of content types that the user is allowed to created for the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to check for content types
    Retrieves:
  • array of content types the user is allowed to create on the place.
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    404 (Not Found)The specified place does not exist
    Since: 3.5

    Get Place Places

    GET /places/{placeID}/places

    Return a paginated list of places contained within the specified place.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    search One or more search terms, separated by commas. You must escape any of the following special characters embedded in the search terms: comma (","), backslash ("\"), left parenthesis ("("), and right parenthesis (")") by preceding them with a backslash. Wildcards can be used, e.g. to search by substring use "*someSubstring*". ?filter=search(test,report)
    tag one or more tags, separated by commas (matching any tag will select a place) ?filter=tag(sales,performance)
    type one or more object types of desired contained places (blog, project, space) separated by commas ?filter=type(blog,project)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this place was created, in ascending order
    dateCreatedDesc Sort by the date this place was created, in descending order
    latestActivityAsc Sort by the date this place had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this place had the most recent activity, in descending order
    titleAsc Sort by place name, in ascending order
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the parent place for which to retrieve contained places
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index at which to start results
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be included in the returned entities
    filterObject[]falseDefined filters to apply when returning places
    sortStringfalseRequested sort order
    Retrieves:
  • Place[] listing the contained places
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this place
    404 (Not Found)The specified place does not exist

    Get Places

    GET /places

    Return a paginated list of places that match the specified filter criteria.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    entityDescriptor one or more objectType,objectID pairs (this filter is likely only useful to those developing the Jive UI itself) ?filter=entityDescriptor(700,1234,14,2345)
    relationship Choose one of the following options:
    • following - Returns places the authenticated user is following. Available since 3.4.
    • following(person uri) - Returns places the specified user is following. Available since 3.10.
    • member - Returns social groups the authenticated user is a member of. Available since 3.4.
    • member(person uri) - Returns social groups the specified user is a member of. Available since 3.10.
    • owner - Returns social groups the authenticated user is an owner of. Available since 3.4.
    • owner(person uri) - Returns social groups the specified user is an owner of. Available since 3.10.
    • recentlyviewed - Returns places that the authenticated user recently viewed. Available since 3.4.
    This filter cannot be combined with other filters.     		?filter=relationship(member) or filter=relationship(following(https://example.jiveon.com/api/core/v3/people/2003))
    search One or more search terms, separated by commas. You must escape any of the following special characters embedded in the search terms: comma (","), backslash ("\"), left parenthesis ("("), and right parenthesis (")") by preceding them with a backslash. Wildcards can be used, e.g. to search by substring use "*someSubstring*". ?filter=search(test,report) or ?filter=search(10\,000)
    tag one or more tags, separated by commas (matching any tag will select a place) ?filter=tag(sales,performance)
    type one or more object types of desired contained places (blog, project, space) separated by commas ?filter=type(blog,project)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this place was created, in ascending order
    dateCreatedDesc Sort by the date this place was created, in descending order
    latestActivityAsc Sort by the date this place had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this place had the most recent activity, in descending order
    titleAsc Sort by place name, in ascending order

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseFilter criteria used to select places
    sortStringfalseRequested sort order
    startIndexIntegerfalseZero-relative index of the first matching place to be returned
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be returned on each place
    Retrieves:
  • Place[] listing the matching places
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access specific places
    Since: 3.0

    Get Place Settings

    GET /places/{placeID}/settings

    Return settings for a specified place, which can be modified by a place admin. Currently settings for Activity and Overview tab visibility are supported.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to return its categories
    Retrieves:
  • Settings
    • Return Status:
    HTTP Status CodeDescription
    403 (Forbidden)You are not allowed to access the specified place
    404 (Not Found)The specified place does not exist

    Get Place Statics

    GET /places/{placeID}/statics

    Return a list of the static resources associated with the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to retrieve static resources.
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Static[]
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    403 (Forbidden)You are not allowed to access static resources for this place
    404 (Not Found)Specified place was not found

    Get Place Suggested Places

    GET /places/{placeID}/suggested/{contentType}

    Return a list of suggested places that the specified content type could be posted by the requesting person, considering the specified place to be the person's "current" place.

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    type one or more object types of desired place objects (blog, group, project, space) ?filter=type(group,project)
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be considered the person's "current" place
    contentTypeStringtrueName of the content type being proposed to publish (document, post, etc.)
    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseFilters on the returned places
    fieldsStringfalseFields to be included in the returned entities
    Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Get Place Tasks

    GET /places/{placeID}/tasks

    Return a paginated list of tasks created for the specified project.

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this content object was created, in ascending order
    dateCreatedDesc Sort by the date this content object was created, in descending order. Default if none was specified.
    latestActivityAsc Sort by the date this content object had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this content object had the most recent activity, in descending order
    titleAsc Sort by content object subject, in ascending order
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the project for which to retrieve its tasks
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index at which to start results
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be included in the returned entities
    sortStringfalseRequested sort order
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Task[] listing the project tasks
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    Since: 3.1

    Get Recommended Places

    GET /places/recommended

    Return a list of recommended places. This feature is only available when Jive has enabled the recommender. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    Query Parameters:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be returned on each place
    Retrieves:
  • Place[] listing the matching places
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    410 (Gone)Recommendation feature is disabled
    Since: 3.1

    Get Root Space

    GET /places/root

    Return the root space for this Jive instance.

    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned on the root space
    Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful

    Get Suggested Places

    GET /places/suggested/{contentType}

    Return a list of suggested places that the specified content type could be posted by the requesting person, without any consideration of the person's "current" place.

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    type one or more object types of desired place objects (blog, group, project, space) ?filter=type(group,project)
    Path Parameters:
    NameTypeRequiredDescription
    contentTypeStringtrueName of the content type being proposed to publish (document, post, etc.)
    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseFilters on the returned places
    fieldsStringfalseFields to be included in the returned entities
    Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Get Trending Places

    GET /places/trending

    Return a list of trending places. This feature is only available when Jive has enabled the recommender. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    Query Parameters:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be returned on each place
    Retrieves:
  • Place[] listing the matching places
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    410 (Gone)Recommendation feature is disabled
    Since: 3.1

    Create Place Following In

    POST /places/{placeID}/followingIn

    Replace the list of Streams in which the requesting user is following this place object.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place object being followed
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned on the updated list of streams
    Takes:
  • JSON array of Stream objects or URIs
    • Retrieves:
  • Stream[] updated list of streams
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)if any input field is malformed
    404 (Not Found)if the specified person does not exist
    Since: 3.3

    Update Place

    PUT /places/{placeID}

    Update an existing place with specified characteristics.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all place types, the following fields are processed: contentTypes, description, displayName, name, parent, tags.
    • For the processed fields, a value present in the incoming entity will cause the corresponding property on the place to be set to the new value, completely replacing any previous value for fields that are arrays or object structures.
    • For the processed fields, a value not present in the incoming entity will cause the corresponding property in the place to remain unchanged.
    • If the parent field is present, and it is different from the current parent, this place will be moved to become a child of the newly specified parent.
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be updated
    Query Parameters:
    NameTypeRequiredDescription
    updatedStringfalseDate and time when this place was most recently updated. Set 'published' param as well. Only set this field when importing content. Since 3.6.
    fieldsStringfalseFields to include in the returned entity
    Takes:
  • Place describing the place to be updated
    • Retrieves:
  • Place representing the updated place
    • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two places of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified place, or to make the requested change in place state

    Update Place Category

    PUT /places/{placeID}/categories/{categoryID}

    Update an existing category with specified characteristics.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place whose category will be updated
    categoryIDStringtrueID of the category to be updated
    Query Parameters:
    NameTypeRequiredDescription
    autoCategorizeStringfalseFlag indicating whether existing content of the place will be categorized under the new category
    fieldsStringfalseFields to be returned (default is @all)
    Takes:
  • Category describing the category to be updated
    • Retrieves:
  • Category representing the updated category
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    404 (Not Found)The ID of the category does not reference an existing category
    403 (Forbidden)You are not allowed to manage categories for the place

    Update Place Settings

    PUT /places/{placeID}/settings

    Updates settings for a specified place. Only a place admin may do this. Currently settings for Activity and Overview tab visibility are supported.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to return its categories
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned (default is @all)
    Takes:
  • Settings describing the settings to apply
    • Retrieves:
  • Settings representing the updated settings
    • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified place, or to make the requested change in place state
    404 (Not Found)The specified place does not exist