Important Notice

The sunset period for the v4 science API endpoints has begun. As of March 30,
2019, new customers will have access only to v5 science endpoints.  v4 endpoints
for managing users and accounts are unaffected and remain available to all
users, existing and new.

URLs for documentation are:

    v5 API: https://analytics.luminoso.com/api/v5/
    v4 API (active): https://analytics.luminoso.com/api/v4/
    v4 API (deprecated): https://analytics.luminoso.com/api/v4_deprecated/

Please note that, while the documentation on deprecated v4 endpoints is
available to everyone, the endpoints themselves are only available to clients
who are still working on moving to v5.

Overview

This API supports the following methods.  Unless otherwise specified, all of
them return a JSON object with two keys, "error" and "result".  If there is no
error, "error" will be null and "result" will be what the "Result" lines below
indicate.  If there is an error, "result" will be null; "error" will be a
JSON object with "code" (a basic error code) and "message" (a human-readable
error message).

Note: several methods refer to "seconds since the epoch".  This refers to Unix
time, which is expressed as a single number of seconds counting up from
00:00:00 UTC, 1 January 1970.  Most programming languages' time libraries
should handle this format.

Another note: we do not strictly enforce the distinction between query strings
(used in GET and DELETE requests) and form data (used in POST, PUT, and PATCH).
For instance, if you used

    PUT /api/v4/projects/<account>/<project_id>/?name=Name

instead of putting the name into the body of the request, the endpoint would
make the change rather than returning an error.  Nevertheless, we do strongly
recommend using the request body for PUT and POST endpoints, due to URL length
limitations.  Needless to say, our Python API client will send things
correctly.

More documentation can be found at http://support.luminoso.com/, including
information on getting started with the API and explanations of error messages;
the documentation below also includes links to several specific pages.

Users

Log in

POST /api/v4/user/login/

    Required parameters:
      username (string)
      password (string)

    Optional parameter:
      [deprecated] token_auth (boolean, default true)
          if specified, must be true (non-token auth no longer exists)

    Result:
      a token object (see GET /user/tokens/<token>/)

    Logs in a user.  For more information, see:
    http://support.luminoso.com/customer/portal/articles/1934917
    

Log out

POST /api/v4/user/logout/

    Result:
      "Logged out."

    Log out of the current session, if the current session is using a
    short-lived token for authentication (i.e., delete the token).  If the
    current session is using a long-lived token, this will return an error
    response.
    

Get user (self)

GET /api/v4/user/profile/

    Result:
      some info about yourself as a user
      (see GET /accounts/<account>/users/<email>/profile/ for details)
    

Modify user (self)

PUT /api/v4/user/profile/

    Required parameter (specify at least one):
      full_name (string)
      default_account (string)

    Result:
      "User updated."

    Updates your user information.
    

Recover password

GET /api/v4/user/password/

    Required parameter:
      email (string)
          the email address (user login) whose password to recover

    Result:
      "OK"

    Sends a password-recovery email to the user with the specified email
    address.

    NOTE: if you supply an email address that is not associated with an
    existing user, no email will be sent!  If you do not receive email after
    using this endpoint, check the address to make sure nothing is misspelled
    and that it is the address you use for Luminoso.  If your address
    is correct and you still receive no email, contact support@luminoso.com
    if you are using the Luminoso Cloud, or your local administrator if you are
    using an on-site installation.
    

Change password

PUT /api/v4/user/password/

    Required parameters:
      old_password (string)
      new_password (string)
          for password requirements, see
          http://support.luminoso.com/customer/portal/articles/1934871

    Result:
      "Password changed."

    Changes the password of the user with the specified email address.

    Note: Changing your password will remove any short-lived tokens you have,
    but will retain your long-lived tokens.
    

Accounts

List accounts

GET /api/v4/accounts/

    Optional parameter:
      permission (string, default "read")
          permission that the user must have on the account

    Result:
      {"accounts": <array of account objects>,
       "default_account": <ID of default account>}

    Returns information for the accounts for which you have the specified
    permission.  See GET /accounts/<account>/ for details.
    

Get account info

GET /api/v4/accounts/<account>/

    Result:
      an account object:

        {"account_id": <account ID>,
         "account_name": <account name>,
         "email": <account email address (only included if you have
                   account_manage permission)>,
         "permissions": <array of your permissions on account>}

    Get info about the account.
    

Modify account info

PUT /api/v4/accounts/<account>/

    Required parameter (specify at least one):
      account_name (string)
          viewable name for this account
      email (string)
          email address for this account (note that this is different from your
          email address as a user; the account's address is where billing
          notifications get sent, etc.)

    Result:
      "Account updated."

    Updates the specified account.
    

Get usage report

GET /api/v4/accounts/<account>/usage/

    Result:
      {"months": [
        {"year": <number>,
         "month": <number>,
         <monitored-thing>: <number>, ...},
       ...],
       "billing_periods": [
         {"start": <number of seconds since the epoch>,
          "end": <number of seconds since the epoch>,
          "first_used": <number of seconds since the epoch or null>,
          "last_used": <number of seconds since the epoch or null>,
          "approved": <boolean>,
          "usage": {<monitored-thing>: <number>, ...},
          "refund": {<monitored-thing>: <number>, ...},
          "limits": {<monitored-thing>: <number or null>, ...},
      }

    Returns usage information for the account, for all months and all billing
    periods, in separate arrays (sorted latest to earliest).

    Each object in the "months" array has a year and a month (e.g., 2013 and 8
    for August 2013) and an entry for each thing that is monitored, indicating
    the number of those things used for that month.

    On each object in the "billing_periods" array, "start" and "end" are epoch
    timestamps that indicate the starts of the days on which the period starts
    and ends.  "first_used" and "last_used" are epoch timestamps of the starts
    of the days on which when the first and last calls in the billing period
    were made (or, if no calls were made in the billing period, both are null).

    "usage", "refund", and "limits" are objects that each have a key for each
    thing that is monitored.  In the "usage" and "refund" objects, the values
    are the number of those things (number of documents, number of projects,
    etc.) that have been used during the billing period or refunded by Client
    Services for the billing period.  In the "limits" object, the values are
    either numbers indicating the upper limit on things that are monitored, or
    null if there is no limit.  Finally, "approved" is a flag set to True for
    billing periods that Client Services have acknowledged as times for which a
    contract exists, and False for periods that cover calls made outside such
    times.
    

Invite user to account

POST /api/v4/accounts/<account>/invite/

    Required parameters:
      email (string)
          email address to invite
      permissions (JSON-encoded array of strings, min length 1)
          which permissions to give user on account

    Result:
      "Email sent."

    Invites a user to join your account, by sending them an email with a link
    that will expire after seven days.  If the user does not already have a
    Luminoso login, they will be invited to create one.

    Note that we currently do not support changing email addresses, so if the
    user already has a Luminoso login, make sure you use the email address that
    they use for their login.
    

List users

GET /api/v4/accounts/<account>/users/

    Result:
      {"members": {<email of user 1>: {"full_name": <full name>,
                                       "permissions": <array of perms>},
                   <email of user 2>: {"full_name": <full name>,
                                       "permissions": <array of perms>},
                   ...},
       "guests": {<email of user 3>: {"full_name": <full name>,
                                      "permissions": <array of perms>},
                  <email of user 4>: {"full_name": <full name>,
                                      "permissions": <array of perms>},
                  ...}}

    Gets the permissions on this account for all users associated with this
    account.  "members" are users owned by this account; they can be
    created/deleted by account admins.  "guests" are users who are not owned by
    this account but who have been given permissions on it by an account admin.

    Note also that there could be other users without account permissions, but
    who have access to some or all of the account's projects.  These users will
    not be included in the results.
    

Delete user

DELETE /api/v4/accounts/<account>/users/<email>/

    Result:
      "User deleted."

    Deletes the user with the specified email address.

    Note: To delete a user, you must have manage permissions on the specified
    account and it must own the user.
    

Get user

GET /api/v4/accounts/<account>/users/<email>/profile/

    Result:
      {"username": <email address>,
       "info": {"full_name": <full name>},
       "permissions": {<account ID 1>: <permissions on group 1>, ...},
       "default_account": <user's default account (possibly null)>,
       "owner": <user's owner account (possibly null)>}

    Gets information about the specified user.  Requires that you have
    account_manage permissions on the specified account and it owns the user.
    

Modify user

PUT /api/v4/accounts/<account>/users/<email>/profile/

    Required parameter (specify at least one):
      full_name (string)
      default_account (string)

    Result:
      "User updated."

    Updates the user's information.  Requires that you have account_manage
    permissions on the specified account and it owns the user.
    

Modify user permissions

PUT /api/v4/accounts/<account>/users/<email>/permissions/

    Required parameter:
      permissions (JSON-encoded array of strings)
          an array of permissions

    Optional parameter:
      reset (boolean, default false)
          if true, removes any existing permissions that the user has on the
          account, and *replaces* them with the new ones; if false, adds the
          new permissions to what the user already has

    Result:
      "Permissions changed."

    Changes the permissions of the user with the specified email address.  The
    user must already have some permissions on this account; if you would like
    to invite a user who only has permissions on a different account, use the
    POST /accounts/<account>/invite/ endpoint.  If the user is owned by the
    account, you cannot remove all of their permissions on the account; in that
    case you should delete the user instead.
    

Tokens

List tokens

GET /api/v4/user/tokens/

    Result:
      list of token objects (see GET /user/tokens/<token>/)

    List the user's API tokens.  There are two types of tokens.  Long-lived
    tokens are intended for programmatic API usage, they never expire (but
    they can be deleted), and each user can currently have at most one.
    Short-lived tokens are obtained by logging in with a username and
    password, they expire after some amount of time (usually two weeks), and
    each user has one per logged-in session.
    

Create token

POST /api/v4/user/tokens/

    Result:
      a token object (see GET /user/tokens/<token>/)

    Create a new long-lived API token.  Currently each user is only allowed
    one long-lived token, so POSTing to /user/tokens/ is only allowed if
    the user has no existing long-lived token.  To replace an existing token,
    first delete it and then create a new one.
    

Get token

GET /api/v4/user/tokens/<token>/

    Result:
      a token object:

        {"token": <token>,
         "type": <"long_lived" or "short_lived">,
         "expiration": <expiration time, in seconds since the epoch>}

    Return information about an API token.  (The expiration time will be
    null for long-lived tokens.)
    

Delete token

DELETE /api/v4/user/tokens/<token>/

    Result:
      "Deleted."

    Delete an API token.  It can be either a short-lived or a long-lived
    token.  After deletion, the token will no longer be usable for making
    API requests (for example, if it was a short-lived token obtained from
    logging in in a web browser, that browser session will get logged out).

    You cannot use this endpoint to delete the token you are using to make
    this request.  If you are using a short-lived token, you can delete it
    using POST /user/logout/.  To delete a long-lived token, you must
    authenticate using a short-lived token.