Posts

Posts in Mavenlink are messages that appear in a workspace, written by participants. Note replies are only included if they are directly related to a Post, replies to events (like Change Orders or Story Created Events) are not included.

Post objects have sixteen readable attributes. They are:

• id - the internal id of the post
• newest_reply_at - the date of the newest reply
• message - the message of the post
• formatted_message - sanitized html representation of message with links, user mentions and emoji images
• has_attachment - whether the post has any attachments
• created_at - the date the post was created
• updated_at - the date the post was last updated
• reply_count - the number of replies to the post
• private - whether this post is private
• user_id - the internal id of the user who made the post
• workspace_id - the internal id of the project workspace this post is associated with
• workspace_type - the class name of the workspace
• reply - whether this post is a reply
• subject_id - if this post is a reply, the internal id of the parent post or object being replied to
• subject_type - the class name of the object being replied to
• story_id - the internal id of the story that this post is linked to

Fetching Posts

You can fetch recent posts across your workspaces from the posts.json endpoint:

curl "https://api.mavenlink.com/api/v1/posts.json"

As with all endpoints, you may ask for specific posts using an only, request additional associated objects with include statements, filter posts, and paginate the results.

Associated Objects

You can include posts' associations with the include param. For example, to include returned posts' creators and stories, you would do the following:

curl "https://api.mavenlink.com/api/v1/posts.json?include=user,story"

In this example, our API will ensure that the returned JSON contains top-level keys called users and stories where you can find associated data by inspecting posts' user_id and story_id fields. See Object Associations to learn more. The following associations can be requested through the API:

• subject - when you include this association, posts that are replies will have a subject_id key referencing their parent post in the posts top-level key
• user - the user object of the post creator, returned in the users top-level key
• workspace - the workspace (project) that owns this post, returned in the workspaces top-level key
• story - linked story (task), returned in the stories top-level key
• replies - replies to this post, returned in the posts top-level key; posts will contain a reply_ids array
• newest_reply - newest reply to this post, available in newest_reply_id and returned in the posts top-level key
• newest_reply_user- user of the newest reply to this post, available in newest_reply_user_id and returned in the users top-level key
• recipients - on private posts, the recipient_ids array contains the ids of recipients, returned in the users top-level key
• google_documents - the post's google document objects, available in google_document_ids and returned in the google_documents top-level key
• attachments - file attachments, available in attachment_ids and returned in the attachments top-level key.

Filtering Posts

The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain posts. The supported filters are:

• parents_only - (default false) results will only include parent posts without including replies by themselves
• workspace_id - only return posts from the given workspace (project)
• from_archived_workspaces - (default false) also return posts from workspaces that have been archived
• created_before - include posts created before the given timestamp (in ISO 8601 format)
• created_after - include posts created after the given timestamp (in ISO 8601 format)
• updated_before - include posts updated before the given timestamp (in ISO 8601 format)
• updated_after - include posts updated after the given timestamp (in ISO 8601 format)

For example to get all posts with a created_date in the year 2000:

curl "https://api.mavenlink.com/api/v1/posts.json?created_at_between=2000-01-01:2000-12-31"

Ordering Posts

Valid orders are:

• newest_reply_at
• id

The default order is newest_reply_at:desc.

Getting a Single Post

As with all resources, you can request either GET /api/v1/posts.json?only=5 or GET /api/v1/posts/5.json. In both cases, default filters will be applied. Therefore, you won't receive Posts from archived workspaces (and will receive a 404 status on the "show" route) unless you provide the from_archived_workspaces:true filter.

Creating a Single New Post

Mavenlink Posts belong to a workspace (project) and take the following parameters:

• message - (required) the content to be created in the new post
• workspace_id - (required) the ID of the Workspace in which the post will be created
• subject_id - (optional, required for replies) the ID of the item the new post is replying to if it is a reply
• subject_type - (optional, required for replies) the type of the item the new post is replying to; accepted values are Post
• story_id - (optional) the ID of the Story (task) that the new post should be linked to
• recipient_ids - (optional) an array of User IDs for whom the post is visible. These users must be participating in the target Workspace and including this parameter will make the post private
• attachment_ids - (optional) an array of PostAttachment IDs that should be associated with the post. Create PostAttachments using the attachments endpoint.

You can create Posts as follows:

curl -X POST -d "post[message]=Hello World" -d "post[workspace_id]=10 "https://api.mavenlink.com/api/v1/posts.json"

or

curl -X POST -H "Content-Type: application/json" --data-binary '{"post": {"workspace_id":10, "message": "Hello World"}}' "https://api.mavenlink.com/api/v1/posts.json"

The response will contain a JSON representation of the newly created post or an error message indicating which arguments are missing or erroneous.

Creating Multiple New Posts

You can create multiple posts in a single request if you send a posts array. An example would be to send a request with the following parameters encoded as application/json:

{"posts": [{"workspace_id": 10, "message": "Posts are cool"}, {"workspace_id": 10, "message": "Don't you like posts?"}]}

Using curl, that request could be sent as:

curl -H "Content-Type: application/json" -d '{"posts": [{"workspace_id": 10, "message": "Posts are cool"}, {"workspace_id": 10, "message": "Don't you like posts?"}]}' "https://api.mavenlink.com/api/v1/posts.json"

Updating an existing Post

You can edit Posts as follows:

curl -X PUT "https://api.mavenlink.com/api/posts/1.json" -d "post[message]=sorry that was a mistake"

The response will contain the JSON representation of the updated post or an error message indicating which arguments are missing or erroneous.

message and story_id can be updated by a an edit.

Destroying an existing Post

You can delete Workspace Posts as follows:

curl -X DELETE "https://api.mavenlink.com/api/v1/posts/2.json"

The response will have no content and HTTP 204 status code if the post has been successfully deleted, or a JSON error message indicating why the post could not be deleted.