.. include:: common.rst

Groups
======

.. http:get:: /api/statusnet/groups/timeline/(int:id)(string:nickname).json

  Show a group’s timeline. Similar to other timeline resources.

  :param int id: |group_id|
  :param string nickname: |group_name|
  :query int count: |status_count|
  :query int since_id: |status_since_id|
  :query int max_id: |status_max_id|

  **Example response**: a list of :ref:`status objects <status_object>`

.. http:get:: /api/statusnet/groups/show/(int:id)(string:nickname).json

  Show details about the group.

  :param int id: |group_id|
  :param string nickname: |group_name|

  **Example response**: :ref:`group_object`

.. http:post:: /api/statusnet/groups/join/(int:id)(string:nickname).json

  Join a group.

  :param int id: |group_id|
  :param string nickname: |group_name|
  :reqheader Authorization: |auth|

  **Example response**: :ref:`group_object`

.. http:post:: /api/statusnet/groups/leave/(int:id)(string:nickname).json

  Leave a group.

  :param int id: |group_id|
  :param string nickname: |group_name|
  :reqheader Authorization: |auth|

  **Example response**: :ref:`group_object`

.. http:post:: /api/statusnet/groups/create.json

  Create a group.

  :form nickname: name of the new group
  :form full_name: (optional) full name associated with the group
  :form homepage: (optional) home page URL associated with the group
  :form location: (optional) The city or country describing where the
                  group is located. The contents are not normalized or
                  geocoded in any way
  :form description: (optional) A description of the group
  :form aliases: (optional) aliases that group has
  :reqheader Authorization: |auth|

  **Example response**: :ref:`group_object`

.. http:get:: /api/statusnet/groups/list_all.json

  List all local groups.

  :query int count: |group_count|

  **Example response**: a list of :ref:`group objects <group_object>`

.. http:get:: /api/statusnet/groups/list.json

  Show the groups which the specified user is a member of.

  :query int count: |group_count|
  :query int user_id: |user_id|
  :query str screen_name: |screen_name|

  **Example response**: a list of :ref:`group objects <group_object>`

.. http:get:: /api/statusnet/groups/membership/(int:id)(string:nickname).json

  List the members of the specified group.

  :param int id: |group_id|
  :param str nickname: |group_name|
  :query int count: |user_count|

  **Example response**: a list of :ref:`user objects <user_object>`

.. http:get:: /api/statusnet/groups/is_member.json

  Show if the specified user is a member of the specified group.

  :query int user_id: |user_id|
  :query str screen_name: |screen_name|
  :query int group_id: (optional) |group_id|
  :query str group_name: (optional) |group_name|

  **Example response**:

  .. sourcecode:: json

    {"is_member": true}

.. http:get:: /api/statusnet/groups/admins/(int:id)(string:nickname).json

  List the admins of the specified group.

  :param int id: |group_id|
  :param str nickname: |group_name|
  :query int count: |user_count|

  **Example response**: a list of :ref:`user objects <user_object>`