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 postnewest_reply_at - the date of the newest replymessage - the message of the postformatted_message - sanitized html representation of message with links, user mentions and emoji imageshas_attachment - whether the post has any attachmentscreated_at - the date the post was createdupdated_at - the date the post was last updatedreply_count - the number of replies to the postprivate - whether this post is privateuser_id - the internal id of the user who made the postworkspace_id - the internal id of the project workspace this post is associated withworkspace_type - the class name of the workspacereply - whether this post is a replysubject_id - if this post is a reply, the internal id of the parent post or object being replied tosubject_type - the class name of the object being replied tostory_id - the internal id of the story that this post is linked toYou 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.
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 keyuser - the user object of the post creator, returned in the users top-level keyworkspace - the workspace (project) that owns this post, returned in the workspaces top-level keystory - linked story (task), returned in the stories top-level keyreplies - replies to this post, returned in the posts top-level key; posts will contain a reply_ids arraynewest_reply - newest reply to this post, available in newest_reply_id and returned in the posts top-level keynewest_reply_user- user of the newest reply to this post, available in newest_reply_user_id and returned in the users top-level keyrecipients - on private posts, the recipient_ids array contains the ids of recipients, returned in the users top-level keygoogle_documents - the post's google document objects, available in google_document_ids and returned in the google_documents top-level keyattachments - file attachments, available in attachment_ids and returned in the attachments top-level key.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 themselvesworkspace_id - only return posts from the given workspace (project)from_archived_workspaces - (default false) also return posts from workspaces that have been archivedcreated_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"
Valid orders are:
newest_reply_atidThe default order is newest_reply_at:desc.
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.
Mavenlink Posts belong to a workspace (project) and take the following parameters:
message - (required) the content to be created in the new postworkspace_id - (required) the ID of the Workspace in which the post will be createdsubject_id - (optional, required for replies) the ID of the item the new post is replying to if it is a replysubject_type - (optional, required for replies) the type of the item the new post is replying to; accepted values are Poststory_id - (optional) the ID of the Story (task) that the new post should be linked torecipient_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 privateattachment_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.
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"
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.
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.