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 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:

Name	Type	Required	Description
fields	String	false	Fields 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 Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to create an announcement

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields 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 Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to create or replace an avatar image

Query Parameters:

Name	Type	Required	Description
uri	String	false	URI 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 Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to create a category

Query Parameters:

Name	Type	Required	Description
autoCategorize	String	false	Flag indicating whether existing content of the place will be categorized under the new category
fields	String	false	Fields 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 Code	Description
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:

Name	Type	Required	Description
fields	String	false	Names 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 Code	Description
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:

Name	Type	Required	Description
fields	String	false	Names 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 Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the project for which to create a task

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields to include in the returned Task

Takes:

Task containing information describing the new project task

Return Status:

HTTP Status Code	Description
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 Place

DELETE /places/{placeID}

Delete the specified place.

Path Parameters:

Name	Type	Required	Description
placeID	String	true	ID of the place to be deleted

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which the avatar image is to be deleted

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which the category is to be deleted
categoryID	String	true	ID of the category to delete

Return Status:

HTTP Status Code	Description
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.

Path Parameters:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to return activities

Query Parameters:

Name	Type	Required	Description
after	String	false	Date and time representing the minimum "last activity in a collection" timestamp for selecting activities (cannot specify both after and before)
before	String	false	Date and time representing the maxium "last activity in a collection" timestamp for selecting activities (cannot specify both after and before)
count	Integer	false	Maximum 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)
fields	String	false	Fields to be included in the returned activities

Retrieves:

Activity[] listing the requested activities

Return Status:

HTTP Status Code	Description
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 Place

GET /places/{placeID}

Return the specified place with the specified fields.

Path Parameters:

Name	Type	Required	Description
placeID	String	true	ID of the place to be returned

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields to be returned

Retrieves:

Place

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to return announcements

Query Parameters:

Name	Type	Required	Description
startIndex	Integer	false	Zero-relative index of the first announcement to be returned
count	Integer	false	Maximum number of announcements to be returned
fields	String	false	Fields to be included in returned announcements

Retrieves:

Announcement[]

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to retrieve the avatar image

Query Parameters:

Name	Type	Required	Description
size	String	false	Requested size ("small", "medium", "large"),default is "large"

Retrieves:

The binary content of the avatar image for the specified place

Return Status:

HTTP Status Code	Description
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 Categories

GET /places/{placeID}/categories

Return categories associated to the specified place.

Path Parameters:

Name	Type	Required	Description
placeID	String	true	ID of the place to return its categories

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields 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:

Name	Type	Required	Description
placeID	String	true	ID of the place that is associated to the category
categoryID	String	true	ID of the category to return

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields to be returned (default is @all)

Retrieves:

Category containing the specified category

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place to check for followers

Query Parameters:

Name	Type	Required	Description
startIndex	Integer	false	Zero-relative index of the first instance to be returned
count	Integer	false	Maximum number of instances to be returned (i.e. the page size)
fields	String	false	Fields to be returned (or `null` for summary fields)

Retrieves:

Person listing people following the specified place

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place to check for following

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields to be included in the returned representation

Retrieves:

Stream[] in which the requesting user is following this place

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID 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 Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the parent place for which to retrieve contained places

Query Parameters:

Name	Type	Required	Description
startIndex	Integer	false	Zero-relative index at which to start results
count	Integer	false	Maximum number of places to be returned
fields	String	false	Fields to be included in the returned entities
filter	Object[]	false	Defined filters to apply when returning places
sort	String	false	Requested sort order

Retrieves:

Place[] listing the contained places

Return Status:

HTTP Status Code	Description
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. member - Returns social groups the authenticated user is a member of. owner - Returns social groups the authenticated user is an owner of. recentlyviewed - Returns places that the authenticated user recently viewed. This filter cannot be combined with other filters. Available since 3.4.	?filter=relationship(member)
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:

Name	Type	Required	Description
filter	Object[]	false	Filter criteria used to select places
sort	String	false	Requested sort order
startIndex	Integer	false	Zero-relative index of the first matching place to be returned
count	Integer	false	Maximum number of places to be returned
fields	String	false	Fields to be returned on each place

Retrieves:

Place[] listing the matching places

Return Status:

HTTP Status Code	Description
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 Statics

GET /places/{placeID}/statics

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

Path Parameters:

Name	Type	Required	Description
placeID	String	true	ID of the place for which to retrieve static resources.

Query Parameters:

Name	Type	Required	Description
fields	String	false	Names of the fields to be returned

Retrieves:

Static[]

Return Status:

HTTP Status Code	Description
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 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:

Name	Type	Required	Description
placeID	String	true	ID of the project for which to retrieve its tasks

Query Parameters:

Name	Type	Required	Description
startIndex	Integer	false	Zero-relative index at which to start results
count	Integer	false	Maximum number of places to be returned
fields	String	false	Fields to be included in the returned entities
sort	String	false	Requested sort order

Retrieves:

Task[] listing the project tasks

Return Status:

HTTP Status Code	Description
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.

Query Parameters:

Name	Type	Required	Description
count	Integer	false	Maximum number of places to be returned
fields	String	false	Fields to be returned on each place

Retrieves:

Place[] listing the matching places

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
fields	String	false	Fields to be returned on the root space

Return Status:

HTTP Status Code	Description
200 (OK)	Request was successful

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.

Query Parameters:

Name	Type	Required	Description
count	Integer	false	Maximum number of places to be returned
fields	String	false	Fields to be returned on each place

Retrieves:

Place[] listing the matching places

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place object being followed

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields 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 Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place to be updated

Query Parameters:

Name	Type	Required	Description
fields	String	false	Fields to include in the returned entity

Takes:

Place describing the place to be updated

Retrieves:

Place representing the updated place

Return Status:

HTTP Status Code	Description
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:

Name	Type	Required	Description
placeID	String	true	ID of the place whose category will be updated
categoryID	String	true	ID of the category to be updated

Query Parameters:

Name	Type	Required	Description
autoCategorize	String	false	Flag indicating whether existing content of the place will be categorized under the new category
fields	String	false	Fields to be returned (default is @all)

Takes:

Category describing the category to be updated

Retrieves:

Category representing the updated category

Return Status:

HTTP Status Code	Description
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

Place

Place Service

Jump to

Create Place

Query Parameters:

Takes:

Retrieves:

Return Status:

Create Place Announcement

Path Parameters:

Query Parameters:

Takes:

Retrieves:

Return Status:

Create Place Avatar

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Create Place Category

Path Parameters:

Query Parameters:

Takes:

Retrieves:

Return Status:

Create Place Static with Data

Takes:

Query Parameters:

Takes:

Retrieves:

Return Status:

Upload New Place Static Data

Query Parameters:

Takes:

Retrieves:

Return Status:

Create Place Task

Path Parameters:

Query Parameters:

Takes:

Return Status:

Since: 3.1

Destroy Place

Path Parameters:

Return Status:

Destroy Place Avatar

Path Parameters:

Return Status:

Destroy Place Category

Path Parameters:

Return Status:

Get Activity

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Get Place

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Get Place Announcements

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Get Place Avatar

Path Parameters:

Query Parameters:

Retrieves:

Return Status:

Get Place Categories

Path Parameters:

Query Parameters:

Retrieves:

Get Place Category

Path Parameters:

Query Parameters:

Retrieves:

Return Status: