habitica/website/views/static/api-v2.jade

doctype html
html
  head
    title Swagger UI
    link(href='//fonts.googleapis.com/css?family=Droid+Sans:400,700', rel='stylesheet', type='text/css')
    link(href='/bower_components/swagger-ui/dist/css/reset.css', media='screen', rel='stylesheet', type='text/css')
    link(href='/bower_components/swagger-ui/dist/css/screen.css', media='screen', rel='stylesheet', type='text/css')
    link(href='/bower_components/swagger-ui/dist/css/reset.css', media='print', rel='stylesheet', type='text/css')
    link(href='/bower_components/swagger-ui/dist/css/screen.css', media='print', rel='stylesheet', type='text/css')

    script(src='/bower_components/swagger-ui/dist/lib/shred.bundle.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/jquery-1.8.0.min.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/jquery.slideto.min.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/jquery.wiggle.min.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/jquery.ba-bbq.min.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/handlebars-1.0.0.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/underscore-min.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/backbone-min.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/swagger.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/swagger-ui.js', type='text/javascript')
    script(src='/bower_components/swagger-ui/dist/lib/highlight.7.3.pack.js', type='text/javascript')
    script(type='text/javascript').
      $(function () {
        window.swaggerUi = new SwaggerUi({
          url: "/api/v2/api-docs",
          dom_id: "swagger-ui-container",
          supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
          onComplete: function(swaggerApi, swaggerUi){
            if(console) {
              console.log("Loaded SwaggerUI")
            }
            $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
          },
          onFailure: function(data) {
            if(console) {
              console.log("Unable to Load SwaggerUI");
              console.log(data);
            }
          },
          docExpansion: "none"
        });

        debugger;

        $('#input_apiKey').change(function() {
          var key = $('#input_apiKey')[0].value;
          console.log("apiKey: " + key);
          if(key && key.trim() != "") {
            console.log("added key " + key);
            window.authorizations.add("apiKey", new ApiKeyAuthorization("x-api-key", key, "header"));
          }
        })
        $('#input_uuid').change(function() {
          var key = $('#input_uuid')[0].value;
          console.log("uuid: " + key);
          if(key && key.trim() != "") {
            console.log("added key " + key);
            window.authorizations.add("uuid", new ApiKeyAuthorization("x-api-user", key, "header"));
          }
        })
        window.swaggerUi.load();
      });
  body.swagger-section
    #header
      .swagger-ui-wrap
        a#logo(href='http://swagger.wordnik.com') Habitica API Documentation

    .swagger-ui-wrap(style='padding:50px')
      form#api_selector
        .input
          input#input_uuid(placeholder='UUID', name='uuid', type='text')
          input#input_apiKey(placeholder='API Key', name='apiKey', type='password')
        //.input
          input#input_baseUrl(placeholder='http://example.com/api', name='baseUrl', type='text')
        //.input
          a#explore(href='#') Explore
      br
      h2 API v3
      p This page contains documentation for version 2 of Habitica's API. A <strong>new API version</strong>, the third, has been released and its documentation can be found <a href="/apidoc">here</a> and an introductory blog post with the most important changes <a href="http://devs.habitica.com">here</a>.
      p API v2 is still available to give time to developers to port their apps and integration to the new API but it's considered <strong>deprecated</strong> and should not be used for new projects. It'll be completely retired shortly.
      br
      h2 Two API Types
      p Habitica's API is meant for two different audiences: (1) extensions and scripts, and (2) full-fledged applications. Extensions and scripts can utilize Habitica's up/down scoring for individual tasks. An example of this in action is the <a href="https://chrome.google.com/webstore/detail/habitrpg/pidkmpibnnnhneohdgjclfdjpijggmjj?hl=en-US">Chrome Extension</a>, which up-scores you for visiting productive websites, and down-scores you for visiting procrastination websites. Other examples currently in use are Pomodoro, Anki, and Github scripts - which up-score you for good behavior and downscore you for bad behavior - <a href="http://habitica.wikia.com/wiki/App_and_Extension_Integrations">see the list</a>. The second API consumer is for full-fledge applications, which need read / write access to the entire user document. An example of this would be Mobile Apps or Desktop application.
      h2 Extensions / Scripts
      p Habitica has a simple API for up-scoring and down-scoring third party Habits: <code>POST /api/v2/user/tasks/{id}/{direction}</code> (headers <code>x-api-user</code> and <code>x-api-key</code> required).
      h4 Example
      p <code>curl -X POST -H "x-api-key: YOUR_API_TOKEN" -H "x-api-user: YOUR_USER_ID" https://habitica.com/api/v2/user/tasks/productivity/up</code>
      p Note: You may need to add <code>--compressed -H "Content-Type:application/json"</code> to your curl if you get errors.
      ul
        li POST to the URL <code>/api/v2/user/tasks/{id}/{direction}</code>
          ul
           li <code>{direction}</code> is 'up' or 'down'
           li <code>{id}</code> is a unique identifier for a Habit, which you make up, consisting of lowercase letters. Try to make it something common, like 'productivity' or 'fitness' - because other services may piggy-back off <em>your</em> Habit. For example, the Chrome extension down-scores a <code>productivity</code> Habit when you visit vice websites (reddit, 9gag, etc). However, Pomodoro up-scores <code>productivity</code> when you complete a Pomodoro task. So the two services share a single Habit to score your overall productivity. If the Habit doesn't yet exist, it is created the first time you POST to this URL.
           li <code>apiToken</code> (POST body) <em>required</em>
      p A more advanced version that allows modification of other types of tasks is available in the /user/tasks/{id}/{direction} route in the full API below.
      h2 Full API
      p All API requests should be prefaced by <code>https://habitica.com</code>. Every authenticated request should include two headers. Your api key (<code>x-api-key</code>) and your user id (<code>x-api-user</code>). Do not include <code>{}</code> braces in your header (<code>-H 'x-api-user: a94b6d9d-6b64-43ae-856c-2c3f211bd426'</code>)
      h2 Requirements:
      p The base-url for all routes is /api/v2. So /user actions will be at https://habitica.com/api/v2/*. You need to send x-api-user and x-api-key headers for each request.
      p For create & edit paths (PUT & POST), you'll need to know the schema of the object you're trying to create or edit. See Schema <a href='https://github.com/HabitRPG/habitrpg/tree/develop/website/server/models' target="_blank">definitions here</a>
      p If any of the documentation is lacking or you're having trouble with it, please post an issue to <a href='https://github.com/HabitRPG/habitrpg/issues' target='_blank'>Github</a>
    #message-bar.swagger-ui-wrap
    #swagger-ui-container.swagger-ui-wrap