Posts

A post represents content that a user shares with the community.

JSON Format

Posts have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the post is created
url string yes no The API url of the post
html_url string yes no The community url of the post
title string no yes The title of the post
details string no yes The details of the post
author_id integer yes* no The id of the author of the post. *Writable on create by Help Center managers -- see Create Post
pinned boolean no no When true, pins the post to the top of its topic
featured boolean no no Whether the post is featured
closed boolean no no Whether further comments are allowed
status string no no The status of the post. Possible values: "planned", "not_planned" , "answered", or "completed"
vote_sum integer yes no The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
vote_count integer yes no The total number of upvotes and downvotes
comment_count integer yes no The number of comments on the post
follower_count integer yes no The number of followers of the post
topic_id integer no yes The id of the topic that the post belongs to
created_at timestamp yes* no When the post was created. *Writable on create by Help Center managers -- see Create Post
updated_at timestamp yes no When the post was last updated
Example
{
  "id": 1635,
  "author_id": 3465,
  "featured": true,
  ...
}

List Posts

  • GET /api/v2/community/posts.json
  • GET /api/v2/community/topics/{id}/posts.json
  • GET /api/v2/community/users/{id}/posts.json

Lists all posts, all posts in a given topic, or all posts by a specific user. When listing by specific user, the posts of the user making the request can be listed by specifying me as the id.

Allowed for
  • Agents
  • End users
  • Anonymous users
Filtering

You can filter the results with the filter_by query string parameter.

GET /api/v2/community/posts.json?filter_by=completed

The filter_by parameter can have one of the following values:

value description
planned list only posts with a status of 'Planned'
not_planned list only posts with a status of 'Not planned'
completed list only posts with a status of 'Completed'
answered list only posts with a status of 'Answered'
none list only posts with a status of 'None'
Sorting

You can sort the results with the sort_by query string parameter.

GET /api/v2/community/posts.json?sort_by=comments

The sort_by parameter can have one of the following values:

value description
created_at order by creation time. Default order
edited_at order by last edit time
updated_at order by last update time
recent_activity order by recent activity on the post
votes order by vote sum
comments order by comment count
Sideloads

You can sideload related records with the include query string parameter. The following sideloads are supported:

Name Will sideload
users authors
topics topics

See Sideloading related records in the Develop Help Center.

Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/users/{id}/posts.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "posts": [
    {
      "id":    35467,
      "title": "How do I open the safe",
      ...
    },
    ...
  ]
}

Show Post

GET /api/v2/community/posts/{id}.json

Gets information about a given post.

Allowed for
  • Agents
  • End users
  • Anonymous users
Sideloads

The following sideloads are supported:

Name Will sideload
users authors
topics topics
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/posts/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "post":
  {
    "id":        35467,
    "author_id": 888887,
    "featured": true,
    ...
  }
}

Create Post

POST /api/v2/community/posts.json

Adds a post to the specified topic.

Allowed for
  • Agents
  • End users

Agents with the Help Center manager role can optionally supply an author_id as part of the post object. If it is provided, the post's author will be set to the value of the author_id key.

Agents with the Help Center manager role can optionally supply a created_at as part of the post object. If it is not provided created_at is set to the current time.

Supplying a notify_subscribers parameter with a value of false will prevent subscribers to the post's topic from receiving a post creation email notification. This can be helpful when bulk importing posts.

Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/posts.json \
  -d '{"post": {"title": "Help!", "details": "My printer is on fire!", "topic_id": 10046}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

Setting the post's author:

curl https://{subdomain}.zendesk.com/api/v2/community/posts.json \
  -d '{"post": {"title": "Help!", "details": "My printer is on fire!", "author_id": 10056, "topic_id": 10046}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
Example Response
Status: 201 Created
Location:
https://{subdomain}.zendesk.com/api/v2/community/posts.json

{
  "post": {
    "id":        35467,
    "author_id": 89567,
    "title":     "Help!",
    "details":   "My printer is on fire!",
    ...
  }
}

Update Post

PUT /api/v2/community/posts/{id}.json

Allowed for
  • Agents
  • The end user who created the post
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/posts/{id}.json \
  -d '{"post": {"title": "Help!", "details": "My printer is on fire!", "topic_id": 10046}}' \
  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
Example Response
Status: 200 OK
Location:
https://{subdomain}.zendesk.com/api/v2/community/posts/{id}.json

{
  "post": {
    "id":        35467,
    "author_id": 89567,
    "title":     "Help!",
    "details":   "My printer is on fire!",
    ...
  }
}

Delete Post

DELETE /api/v2/community/posts/{id}.json

Allowed for
  • Agents
  • The end user who created the post
Using curl
curl https://{subdomain}.zendesk.com/api/v2/community/posts/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content