Welcome to our API documentation! Our API will enable you to write programs that are able to access a user's account and perform certain operations on them. Our API calls are detailed below.

general information

All our API calls are made using POST requests and return standard JSON. Many required parameters and return codes are common between requests, and these are noted in any call's documentation.

Caveat: Please make sure your requests are made to the appropriate domain and that they include the trailing slash, otherwise you will get 301 redirect messages.

/api/getkey/

This function returns the user's API key. This is necessary for performing requests that require a key. Note that the user must either be logged in to historious at the time of the call, or you need to specify a valid username/password pair. Otherwise, this call will fail. The purpose of this call is to allow developers to easily and unambiguously retrieve a signed-in user's key without any interaction required by the user.

    POST parameters:
    agent - Your program's user agent string (a string that describes your
            program, e.g. "historious foo.bar extension v1.2"). You are
            free to use anything you want for this, but please make it
            descriptive.
    username - Optional. The user's username.
    password - Optional. The user's password. If these credentials are specified,
                         it is not necessary to log the user in before calling this.

    Return codes:
    2 - Invalid user or user not logged in.
    2 - Invalid request.
    other int - Reserved error code.
    string - The user's key.
    

/api/add/

This function historifies a document to the user's account. This is equivalent to a a user clicking the bookmarklet on a site, or adding a URL from the "historify" page. The user does not need to be logged in for this API call, as the key will suffice.

Requires an API key.

    URL parameters:
    key - The user's API key (e.g. "/api/add/?key=userkey").

    POST parameters:
    agent - Your program's user agent string (a string that describes your
            program, e.g. "historious foo.bar extension v1.2").
    url - The historified page's URL (e.g. "https://historio.us/search/).
    source - This is optional, but highly recommended. This parameter should
             be the complete HTML source of the historified page, as it
             arrives from the server. If this exists, historious will
             use it to index the page, otherwise it will attempt to get the
             page itself. This is almost certainly suboptimal, as it might
             fail if the page is behind paywalls or registration pages.
    title - A title for the historified page (will only work for subscribers).
    tags - Tags to set for the historified page (will only work for subscribers).

    Return codes:
    0 - Success.
    1 - URL has already been historified.
    2 - Invalid API key.
    3 - Invalid request or site URL.
    4 - User has reached the site limit.
    other int - Reserved error code.
    

/api/gettags/

This function returns all the tags a user currently has (on any of their documents). The user does not need to be logged in for this API call, as the key will suffice.

Requires an API key.

    URL parameters:
    key - The user's API key (e.g. "/api/gettags/?key=userkey").

    POST parameters:
    agent - Your program's user agent string (a string that describes your
            program, e.g. "historious foo.bar extension v1.2").

    Return codes:
    [tag list] - The list of the user's tags.
    2 - Invalid API key.
    3 - Invalid request or site URL.
    other int - Reserved error code.
    

/api/userinfo/

This function returns various information about the user. The user does not need to be logged in for this API call, as the key will suffice.

Requires an API key.

    URL parameters:
    key - The user's API key (e.g. "/api/userinfo/?key=userkey").

    POST parameters:
    agent - Your program's user agent string (a string that describes your
            program, e.g. "historious foo.bar extension v1.2").

    Return codes:
    {user info} - A dictionary of the user's information.
    2 - Invalid API key.
    3 - Invalid request or site URL.
    other int - Reserved error code.