Warning

This is the documentation for the REST interface. Unfortunately it is outdated and parts of the interface may not work anymore.

REST Resources

/instance - Group/Organization Instances

index

• List all existing and non-hidden instances.
• URL: http://[instance].adhocracy.cc/instance[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: instances_

create

• Create a new instance for a group or organization.
• URL: http://[instance].adhocracy.cc/instance[.format]
• Method: POST
• Formats: html, json
• Authentication: yes
• Parameters:
  • key: A unique identifier for the instance. Short lower-case alpha-numeric text. This cannot be edited after the instance creation.
  • label: A title for the instance.
  • description: Short description for the instance, e.g. a mission statement.

show

• View an instance’s home page or base data
• URL: http://[instance].adhocracy.cc/instance/[key][.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Note: If no instance subdomain has been specified, this will 302 to the actual instance.

update

• Update some of an instance’s properties.
• URL: http://[instance].adhocracy.cc/instance/[key][.format]
• Method: PUT
• Formats: html, json
• Authentication: yes
• Parameters:
  • label: A title for the instance.
  • description: Short description for the instance, e.g. a mission statement.
  • required_majority: The percentage of voters required for the adoption of a proposal (e.g. 0.66 for 66%).
  • activation_delay: Delay (in days) that a proposal needs to maintain a majority to be adopted.
  • allow_adopt: Whether to allow adoption polls on proposals (bool).
  • allow_delegate: Whether to enable delegated voting (bool).
  • allow_index: Allow search engine indexing (via robots.txt, bool).
  • hidden: Show instance in listings.
  • default_group: Default group for newly joined members (one of: observer, advisor, voter, supervisor).

delete

• Delete an instance and all contained entities.
• URL: http://[instance].adhocracy.cc/instance/[key][.format]
• Method: DELETE
• Formats: html, json
• Authentication: yes (requires global admin rights)
• Note: This will also delete all contained items, such as proposals, delegations, polls or comments.

activity

• Retrieve a list of the latest events relating to this instance.
• URL: http://[instance].adhocracy.cc/instance/[key]/activity[.format]
• Method: GET
• Formats: html, rss
• Authentication: no
• Pager prefix: events_

join

• Make the authenticated user a member of this Instance.
• URL: http://[instance].adhocracy.cc/instance/[key]/join[.format]
• Method: GET
• Formats: html
• Authentication: yes
• Note: Fails if the user is already a member of the instance.

leave

• Terminate the authenticated user’s membership in this Instance.
• URL: http://[instance].adhocracy.cc/instance/[key]/leave[.format]
• Method: POST
• Formats: html
• Authentication: yes
• Note: Fails if the user is not a member of the instance.

/user - User Management

index

• List all users with an active membership in the specified instance.
• URL: http://[instance].adhocracy.cc/user[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: users_
• Parameters:
  • users_q: A search query to filter with.
  • users_filter: Filter by membership group (only in an instance context).
• Note: If no instance is specified, all registered users will be returned.

create

• Create a new user.
• URL: http://[instance].adhocracy.cc/user[.format]
• Method: POST
• Formats: html, json
• Authentication: no
• Parameters:
  • user_name: A unique user name for the new user.
  • email: An email, must be validated.
  • password: A password, min. 3 characters.
  • password_confirm: Must be identical to password.
• Note: Does not require an instance to be specified. If an instance is selected, the user will also become a member of that instance.

show

• View an user’s home page and activity stream,
• URL: http://[instance].adhocracy.cc/user/[user_name][.format]
• Method: GET
• Formats: html, json, rss
• Authentication: no
• Note: Also available outside of instance contexts.

update

• Update the user’s profile and settings.
• URL: http://[instance].adhocracy.cc/user/[user_name][.format]
• Method: PUT
• Formats: html, json
• Authentication: yes (either to own user or with user management permissions)
• Parameters:
  • display_name: Display name, i.e. the real name to be shown in the application.
  • email: E-Mail address. Must be re-validated when changed.
  • locale: A locale, currently: de_DE, en_US or fr_FR.
  • password: A password, min. 3 characters.
  • password_confirm: Must be identical to password.
  • bio: A short bio, markdown-formatted.
  • email_priority: Minimum priority level for E-Mail notifications to be sent (0-6).
  • twitter_priority: Minimum priority level for Twitter direct message notifications to be sent (0-6).

delete

• Delete an user. Not implemented

votes

• Retrieve a list of the decisions that were made by this user.
• URL: http://[instance].adhocracy.cc/user/[user_name]/votes[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: decisions_
• Note: Does not include rating polls, limited to adoption polls.

delegations

• Retrieve a list of the delegations that were created by this user.
• URL: http://[instance].adhocracy.cc/user/[user_name]/delegations[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: delegations_ (``json`` view only)
• Note: In html, lists both incoming and outgoing delegations. When rendered as json, this only includes outgoing delegations.

instances

• A list of all non-hidden instances in which the user is a member.
• URL: http://[instance].adhocracy.cc/user/[user_name]/instances[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: instances_

proposals

• A list of all proposals that the user has introduced.
• URL: http://[instance].adhocracy.cc/user/[user_name]/proposals[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: proposals_

groupmod

• Modify a user’s membership in the current instance
• URL: http://[instance].adhocracy.cc/user/[user_name]/proposals[.format]
• Method: GET
• Formats: html
• Authentication: yes (requires instance admin privileges)
• Parameters:
  • to_group: Target group (one of: observer, advisor, voter, supervisor).

kick

• Terminate a user’s membership in the current instance
• URL: http://[instance].adhocracy.cc/user/[user_name]/proposals[.format]
• Method: GET
• Formats: html
• Authentication: yes (requires instance admin privileges)
• Note: Since the user can re-join at any time, this is largely a symbolic action.

/proposal - Proposal drafting

index

• List all existing proposals in the given instance.
• URL: http://[instance].adhocracy.cc/proposal[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: proposals_
• Parameters:
  • proposals_q: A search query to filter with.
  • proposals_state: Filter by state (one of: draft, polling, adopted). Only available if adoption polling is enabled in the selected instance.

create

• Create a new proposal.
• URL: http://[instance].adhocracy.cc/proposal[.format]
• Method: POST
• Formats: html, json
• Authentication: yes
• Parameters:
  • label: A title for the proposal.
  • text: Goals of the proposal.
  • tags: Comma-separated or space-separated tag list to be applied to the proposal.
  • alternative (multiple values): IDs of any proposals that should be marked as an alternative to this proposal.

show

• View an proposals’s goal page
• URL: http://[instance].adhocracy.cc/proposal/[id][.format]
• Method: GET
• Formats: html, json
• Authentication: no

update

• Update some of a proposal’s properties.
• URL: http://[instance].adhocracy.cc/proposal/[id][.format]
• Method: PUT
• Formats: html, json
• Authentication: yes
• Parameters:
• label: A title for the proposal.
• alternative (multiple values): IDs of any proposals that should be marked as an alternative to this proposal.
• Note: The goal description and tag list are edited separately.

delete

• Delete a proposal and any contained entities.
• URL: http://[instance].adhocracy.cc/proposal/[id][.format]
• Method: DELETE
• Formats: html, json
• Authentication: yes (requires instance admin rights)
• Note: This will also delete all contained items, such as comments and delegations.

delegations

• Retrieve a list of the delegations that exist regarding this proposal.
• URL: http://[instance].adhocracy.cc/proposal/[id]/delegations[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: delegations_

canonicals

• Retrieve a list of canonical comments regarding the proposal. Canonical comments are listed as “provisions” in the UI.
• URL: http://[instance].adhocracy.cc/proposal/[id]/delegations[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Note: No pager.

alternatives

• Retrieve a list of the alternatives that exist regarding this proposal.
• URL: http://[instance].adhocracy.cc/proposal/[id]/alternatives[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: proposals_

activity

• Retrieve a list of events within the scope of the given proposal.
• URL: http://[instance].adhocracy.cc/proposal/[id]/activity[.format]
• Method: GET
• Formats: html, rss
• Authentication: no
• Pager prefix: events_

adopt

• Trigger an adoption poll regarding this proposal.
• URL: http://[instance].adhocracy.cc/proposal/[id]/adopt[.format]
• Method: POST
• Formats: html
• Authentication: yes
• Note: Requires at least one canonical comment. Adoption polls must be enabled on the instance level.

tag

• Apply an additional tag to a proposal (or support an existing tag).
• URL: http://[instance].adhocracy.cc/proposal/[id]/tag[.format]
• Method: GET
• Formats: html
• Authentication: yes
• Parameters:
  • text: Comma-separated or space-separated tag list to be applied to the proposal.

untag

• Remove a tag association (tagging) from a proposal.
• URL: http://[instance].adhocracy.cc/proposal/[id]/untag[.format]
• Method: GET
• Formats: html
• Authentication: yes
• Parameters:
  • tagging: ID of the tagging association to be removed.
• Note: Only taggings created by the user can be removed.

/poll - Poll data and voting

show

• View a poll, listing the current decisions and offering a chance to vote.
• URL: http://[instance].adhocracy.cc/poll/[id][.format]
• Method: GET
• Formats: html, json
• Authentication: no

delete

• End a poll and close voting.
• URL: http://[instance].adhocracy.cc/poll/[id][.format]
• Method: DELETE
• Formats: html, json
• Authentication: yes
• Note: This will only work for adoption polls, rating polls cannot be terminated.

votes

• Retrieve a list of the decisions that were made regarding this poll.
• URL: http://[instance].adhocracy.cc/poll/[id]/votes[.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: decisions_
• Parameters:
  • result: Filter for a specific decision, i.e. -1 (No), 1 (Yes), 0 (Abstained).

rate

• Vote in the poll via rating.
• URL: http://[instance].adhocracy.cc/poll/[id]/rate[.format]
• Method: POST
• Formats: html, json
• Authentication: yes
• Note: This implements relative voting, i.e. if a user has previously voted -1 and now votes 1, the result will be 0 (a relative change). Used for comment up-/downvoting. Unlike vote, this will also trigger an automated tallying of the poll. It is thus slower, especially for large polls.

vote

• Vote in the poll.
• URL: http://[instance].adhocracy.cc/poll/[id]/vote[.format]
• Method: POST
• Formats: html, json
• Authentication: yes
• Note: This does not trigger tallying. Thus a subsequent call to show might yield an incorrect tally until a server background job has run.

/comment - Commenting and comment history

index

• List all existing comments.
• URL: http://[instance].adhocracy.cc/comment[.format]
• Method: GET
• Formats: json
• Authentication: no
• Pager prefix: comments_

create

• Create a new comment within a specified context.
• URL: http://[instance].adhocracy.cc/comment[.format]
• Method: POST
• Formats: html, json
• Authentication: yes
• Parameters:
  • topic: ID of the Delegateable to which this comment is associated.
  • reply: A parent comment ID, if applicable.
  • canonical (bool): Specify whether this is part of the implementation description of the proposal to which it will be associated.
  • text: The comment text, markdown-formatted.
  • sentiment: General tendency of the comment, i.e. -1 for negative, 0 for neutral and 1 for a supporting argument.

show

• View a comment separated out of their context.
• URL: http://[instance].adhocracy.cc/comment/[id][.format]
• Method: GET
• Formats: html, json
• Authentication: no

update

• Create a new revision of the given comment.
• URL: http://[instance].adhocracy.cc/comment/[id][.format]
• Method: PUT
• Formats: html, json
• Authentication: yes
• Parameters:
  • text: The comment text, markdown-formatted.
  • sentiment: General tendency of the comment, i.e. -1 for negative, 0 for neutral and 1 for a supporting argument.

delete

• Delete a comment.
• URL: http://[instance].adhocracy.cc/comment/[id][.format]
• Method: DELETE
• Formats: html, json
• Authentication: yes
• Note: Comments can only be deleted by non-admins if they have not yet been edited.

history

• List all revisions of the specified comment.
• URL: http://[instance].adhocracy.cc/comment/[id]/history[.format]
• Method: GET
• Formats: html, json
• Authentication: yes
• Pager prefix: revisions_

revert

• Revert to an earlier revision of the specified comment.
• URL: http://[instance].adhocracy.cc/comment/[id]/revert[.format]
• Method: GET
• Formats: html, json
• Authentication: yes
• Parameters:
  • to: Revision ID to revert to.
• Note: This will actually create a new revision containing the specified revision’s text.

/delegation - Vote delegation management

index

• List all existing delegations (instance-wide).
• URL: http://[instance].adhocracy.cc/delegation[.format]
• Method: GET
• Formats: json, dot
• Authentication: no
• Pager prefix: delegations_
• Note: The dot format produces a graphviz file.

create

• Create a new delegation to a specified principal in a given scope.
• URL: http://[instance].adhocracy.cc/delegation[.format]
• Method: POST
• Formats: html, json
• Authentication: yes
• Parameters:
  • scope: ID of the Delegateable which will be the delegation’s scope.
  • agent: User name of the delegation recipient.
  • replay: Whether or not to re-play all of the agents previous decisions within the scope.

show

• View the delegation.
• URL: http://[instance].adhocracy.cc/delegation/[id][.format]
• Method: GET
• Formats: html, json
• Authentication: no
• Pager prefix: decisions_
• Note: For json this will return a tuple of the actual serialized delegation and a list of decisions.

delete

• Revoke a the delegation.
• URL: http://[instance].adhocracy.cc/delegation/[id][.format]
• Method: DELETE
• Formats: html, json
• Authentication: yes
• Note: Can only be performed by the delegation’s principal.