discourse_swagger.yml

swagger: '2.0'

#Basic information
info:
  version: 1.5.0-beta14
  title: Discourse REST API Specificatiom
  description: This specification describes the [Discourse](http://discourse.org) REST API and can be used to generate clients using the [Swagger](http://swagger.io) toolset.


#Meta types for API
produces:
  - application/json
consumes:
  - application/json


#Defines available security objects
securityDefinitions:
  api_username:
    name: api_username
    type: apiKey
    in: query
    description: Username of user making request
  api_key:
    name: api_key
    type: apiKey
    in: query
    description: Generated API key. Must have been generated for the username passed as `api_username`

#Defines default security objects for operations
security:
  - api_username: []
  - api_key: []


#List of operations available for the Discourse REST API
paths:

  #Request site information
  /site.json:
    get:
      operationId: getSite
      description: |
        Gets site information, including
        1. Categories
        2. Groups
        3. Post action types
        4. Topic flag types

        and many other properties related to how the Discourse site is set up

      security:
        - api_username: []
        - api_key: []

      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Site'

  /categories.json:
    get:
      operationId: getCategories
      description: |
        Gets detailed information about all categories available to the user making the request

      security:
        - api_username: []
        - api_key: []

      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/CategoriesResponse'

  /c/{id}.json:
    get:
      operationId: getCategory
      description: |
        Gets detailed information and topics for a specific category

      parameters:
        - name: id
          type: string
          description: Category slug
          in: path
          required: true

      security:
        - api_username: []
        - api_key: []

      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/CategoryResponse'

  /t/{id}.json:
    get:
      operationId: getTopic
      description: |
        Gets detailed information and posts for a specific topic

      parameters:
        - name: id
          type: string
          description: Topic slug
          in: path
          required: true

      security:
        - api_username: []
        - api_key: []

      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/TopicView'

#Definitions of types used in the REST calls (parameters and responses)
definitions:

  #Serialized by site_serializer.rb
  Site:
    properties:

      archetypes:
        description: Describes the available post archetypes
        type: array
        items:
          $ref: '#/definitions/Archetype'

      default_archetype:
        description: The post archetype used by default
        type: string

      categories:
        type: array
        items:
          $ref: '#/definitions/BasicCategory'

      uncategorized_category_id:
        description: The category ID used for uncategorized posts
        type: integer

      notification_types:
        description: Map of string to integer listing the available notification types
        type: object
        additionalProperties:
          type: integer

      post_types:
        description: Map of string to integer listing the available post types
        type: object
        additionalProperties:
          type: integer

      groups:
        description: Lists the available groups
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string

      filters:
        description: Lists the available post filters (latest, new, unread etc.)
        type: array
        items:
          type: string

      periods:
        description: Lists the available time periods for filtering posts (all, yearly, daily etc.)
        type: array
        items:
          type: string

      top_menu_items:
        description: Lists the menu items shown at the top of the page for logged in users
        type: array
        items:
          type: string

      anonymous_top_menu_items:
        description: Lists the menu items shown at the top of the page for anonomous visitors
        type: array
        items:
          type: string

      is_readonly:
        description: Indicates whether the site is in read-only mode
        type: boolean

      disabled_plugins:
        description: Lists the plugins that are currently disabled
        type: array
        items:
          type: string

      suppressed_from_homepage_category_ids:
        description: Declares which categories are suppressed from the front page
        type: array
        items:
          type: integer

      post_action_types:
        description: Lists the actions users can apply to posts (like, bookmark, off_topic etc.)
        type: array
        items:
          $ref: '#/definitions/PostActionType'

      topic_flag_types:
        description: Lists the flags that can be applied to topics (inappropriate, spam etc.)
        type: array
        items:
          $ref: '#/definitions/TopicFlagType'

      trust_levels:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string

      user_fields:
        type: array
        items:
          $ref: '#/definitions/UserField'


      user_field_max_length:
        type: integer

  #Serialized by archetype_serializer.rb
  Archetype:
    properties:
      id:
        type: string
      name:
        type: string
      options:
        type: array
        items:
          type: string
  #Serialized by basic_category_serializer.rb
  BasicCategory:
    properties:
      id:
        type: integer
      name:
        type: string
      color:
        type: string
      text_color:
        type: string
      slug:
        type: string
      topic_count:
        type: integer
      post_count:
        type: integer
      position:
        type: integer
      description:
        type: string
      description_text:
        type: string
      topic_url:
        type: string
      logo_url:
        type: string
      background_url:
        type: string
      read_restricted:
        type: boolean
      permission:
        type: integer
      notification_level:
        type: integer
      can_edit:
        type: boolean
      topic_template:
        type: string
      has_children:
        type: boolean

  #Serialized by category_detailed_serializer.rb
  CategoryDetailed:
    allOf:
      - $ref: '#/definitions/BasicCategory'
      - type: object
        properties:
          topics_day:
            type: integer
          topics_week:
            type: integer
          topics_month:
            type: integer
          topics_year:
            type: integer
          posts_day:
            type: integer
          posts_week:
            type: integer
          posts_month:
            type: integer
          posts_year:
            type: integer
          description_excerpt:
            type: string
          featured_user_ids:
            type: array
            items:
              type: integer

  #Serialized by post_action_type_serializer.rb
  PostActionType:
    properties:
      name_key:
        type: string
      name:
        type: string
      description:
        type: string
      long_form:
        type: string
      is_flag:
        type: boolean
      icon:
        type: string
      id:
        type: integer
      is_custom_flag:
        type: boolean

  #Serialized by post_action_type_serializer.rb
  TopicFlagType:
    allOf:
      - $ref: '#/definitions/PostActionType'

  #Serialized by user_field_serializer.rb
  UserField:
    properties:
      id:
        type: integer
      name:
        type: string
      description:
        type: string
      field_type:
        type: string
      editable:
        type: boolean
      required:
        type: boolean
      show_on_profile:
        type: boolean
      position:
        type: integer
      options:
        description: Only available when 'field_type' is 'dropdown'
        type: array
        items:
          type: string

  #Serialized by category_list_serializer.rb
  CategoryList:
    properties:
      can_create_category:
        type: boolean
      can_create_topic:
        type: boolean
      draft:
        type: string
      draft_key:
        type: string
      draft_sequence:
        type: integer
      categories:
        type: array
        items:
          $ref: '#/definitions/CategoryDetailed'

  #Serialized by basic_user_serializer.rb
  BasicUser:
    properties:
      id:
        type: integer
      username:
        type: string
      avatar_template:
        type: string

  #Not sure who serializes this
  CategoriesResponse:
    properties:
      featured_users:
        type: array
        items:
          $ref: '#/definitions/BasicUser'
      category_list:
        $ref: '#/definitions/CategoryList'

  #Not sure who serializes this
  CategoryResponse:
    properties:
      users:
        type: array
        items:
          $ref: '#/definitions/BasicUser'
      topic_list:
        $ref: '#/definitions/TopicList'

  #Serialized by topic_list_serializer.rb
  TopicList:
      properties:
      properties:
        can_create_topic:
          type:       boolean
        draft:
          type:       string
        draft_key:
          type:       string
        draft_sequence:
          type:       integer
        per_page:
          type:       integer
        topics:
          type:       array
          items:
            $ref: '#/definitions/TopicListItem'


  #Serialized by basic_topic_serializer.rb
  BasicTopic:
    properties:
      id:
        type:       integer
      title:
        type:       string
      fancy_title:
        type:       string
      slug:
        type:       string
      posts_count:
        type:       integer


  #Serialized by listable_topic_serializer.rb
  ListableTopic:
    allOf:
      - $ref: '#/definitions/BasicTopic'
      - type: object
        properties:
          reply_count:
            type:       integer
          highest_post_number:
            type:       integer
          image_url:
            type:       string
          created_at:
            type:       string
          last_posted_at:
            type:       string
          bumped:
            type:       boolean
          bumped_at:
            type:       string
          unseen:
            type:       boolean
          last_read_post_number:
            type:       integer
          unread:
            type:       integer
          new_posts:
            type:       integer
          pinned:
            type:       boolean
          unpinned:
            type:       boolean
          visible:
            type:       boolean
          closed:
            type:       boolean
          archived:
            type:       boolean
          notification_level:
            type:       integer
          bookmarked:
            type:       boolean
          liked:
            type:       boolean

  #Serialized by topic_list_item_serializer.rb
  TopicListItem:
    allOf:
    - $ref: '#/definitions/ListableTopic'
    - type: object
      properties:
        views:
          type:       integer
        like_count:
          type:       integer
        has_summary:
          type:       boolean
        archetype:
          type:       string
        last_poster_username:
          type:       string
        category_id:
          type:       integer
        pinned_globally:
          type:       boolean
        posters:
          type:       array
          items:
            $ref: '#/definitions/TopicPoster'
        participants:
          type:       array
          items:
            $ref: '#/definitions/TopicPoster'


  #Serialized by topic_poster_serializer.rb
  TopicPoster:
    properties:
      extras:
        type:       string
      description:
        type:       string
      user_id:
        type:       integer

  #Serialized by topic_view_serializer.rb
  TopicView:
    properties:
      post_stream:
        $ref: '#/definitions/PostStream'
      id:
        type: integer
      title:
        type: string
      fancy_title:
        type: string
      posts_count:
        type: integer
      created_at:
        type: string
      views:
        type: integer
      reply_count:
        type: integer
      participant_count:
        type: integer
      like_count:
        type: integer
      last_posted_at:
        type: string
      visible:
        type: boolean
      closed:
        type: boolean
      archived:
        type: boolean
      has_summary:
        type: boolean
      archetype:
        type: string
      slug:
        type: string
      category_id:
        type: integer
      word_count:
        type: integer
      deleted_at:
        type: string
      user_id:
        type: integer
      draft:
        type: string
      draft_key:
        type: string
      draft_sequence:
        type: integer
      posted:
        type: boolean
      unpinned:
        type: boolean
      pinned_globally:
        type: boolean
      pinned:
        type: boolean
      pinned_at:
        type: string
      pinned_until:
        type: string

      #There is a TODO in the source code to move this to its own serializer, but for now we'll leave it here
      details:
        type: object
        properties:
          auto_close_at:
            type: string
          auto_close_hours:
            type: string
          auto_close_based_on_last_post:
            type: boolean
          created_by:
            $ref: '#/definitions/BasicUser'
          last_poster:
            $ref: '#/definitions/BasicUser'
          participants:
            type: array
            items:
              $ref: '#/definitions/TopicPostCount'
          suggested_topics:
            type: array
            items:
              $ref: '#/definitions/SuggestedTopic'
          links:
            type: array
            items:
              $ref: '#/definitions/TopicLink'
          notification_level:
            type: integer
          notifications_reason_id:
            type: integer
          can_move_posts:
            type: boolean
          can_edit:
            type: boolean
          can_recover:
            type: boolean
          can_remove_allowed_users:
            type: boolean
          can_invite_to:
            type: boolean
          can_create_post:
            type: boolean
          can_reply_as_new_topic:
            type: boolean
          can_flag_topic:
            type: boolean
          #END details

      highest_post_number:
        type: integer
      last_read_post_number:
        type: integer
      deleted_by:
        type: string
      has_deleted:
        type: boolean
      actions_summary:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
            count:
              type: integer
            hidden:
              type: boolean
            can_act:
              type: boolean
      chunk_size:
        type: integer
      bookmarked:
        type: boolean

  #Serialized by post_stream_serializer_mixin.rb
  PostStream:
    properties:
      posts:
        type: array
        items:
          $ref: '#/definitions/Post'

  #Serialized by basic_post_serializer.rb
  BasicPost:
    properties:
      id:
        type: integer
      name:
        type: string
      username:
        type: string
      avatar_template:
        type: string
      created_at:
        type: string
      cooked:
        type: string

  #Serialized by post_serializer.rb
  Post:
    allOf:
    - $ref: '#/definitions/BasicPost'
    - type: object
      properties:
        post_number:
          type: integer
        post_type:
          type: integer
        updated_at:
          type: string
        reply_count:
          type: integer
        reply_to_post_number:
          type: integer
        quote_count:
          type: integer
        avg_time:
          type: string
        incoming_link_count:
          type: integer
        reads:
          type: integer
        score:
          type: number
        yours:
          type: boolean
        topic_id:
          type: integer
        topic_slug:
          type: string
        display_username:
          type: string
        primary_group_name:
          type: string
        version:
          type: integer
        can_edit:
          type: boolean
        can_delete:
          type: boolean
        can_recover:
          type: boolean
        can_wiki:
          type: boolean
        read:
          type: boolean
        user_title:
          type: string
        actions_summary:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              can_act:
                type: boolean
        moderator:
          type: boolean
        admin:
          type: boolean
        staff:
          type: boolean
        user_id:
          type: integer
        hidden:
          type: boolean
        hidden_reason_id:
          type: integer
        trust_level:
          type: integer
        deleted_at:
          type: string
        user_deleted:
          type: boolean
        edit_reason:
          type: string
        can_view_edit_history:
          type: boolean
        wiki:
          type: boolean

  #Serialized by suggested_topic_serializer.rb
  SuggestedTopic:
    allOf:
    - $ref: '#/definitions/ListableTopic'
    - type: object
      properties:
        archetype:
          type: string
        like_count:
          type: integer
        views:
          type: integer
        category_id:
          type: integer


  TopicPostCount:
    allOf:
      - $ref: '#/definitions/BasicUser'
      - type: object
        properties:
          post_count:
            type: integer

  TopicLink:
    properties:
      url:
        type: string
      title:
        type: string
      fancy_title:
        type: string
      internal:
        type: boolean
      attachment:
        type: boolean
      reflection:
        type: boolean
      clicks:
        type: integer
      user_id:
        type: integer
      domain:
        type: string