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.

More documentation can be found at http://wiki.services.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.


  

Projects

List projects

GET /v4/projects/

    Optional parameter:
      name - if specified, return only projects with that name
             (useful if you know the name but forget the project ID)

    Result: [<metadata object>, ...]

    Returns a list of metadata objects for a user's available projects. See
    the documentation for GET /projects/<account>/<project_id>/ for details
    about metadata objects.
    
      

List account's projects

GET /v4/projects/<account>/

    Optional parameter:
      name - if specified, return only projects with that name
             (useful if you know the name but forget the project ID)

    Result: [<metadata object>, ...]

    Returns list of metadata objects for an account's available projects.  See
    the documentation for GET /projects/<account>/<project_id>/ for details
    about metadata objects.
    
      

Get project info

GET /v4/projects/<account>/<project_id>/

    Result: {"project_id": <project ID>,
             "owner": <ID of account that owns the project>,
             "account_name": <name of account that owns the project>,
             "creator": <user who created the project>,
             "permissions": <your permissions on the project>,
             "name": <name of the project>,
             "description": <text description of the project>,
             "creation_date": <time of the project's creation>,
             "last_metaupdate": <time of the last change to the project>,
             "last_update": <time of the last assoc space build>,
             "axes": <number of dimensions of the assoc space>,
             "current_assoc_version": <current version of the assoc space>,
             "running_jobs": <a (possibly empty) list of numbers>,
             "counts": <a mapping from subsets to the # of docs in the subset>}

    General metadata for a project. Times are floating-point numbers
    representing seconds since the epoch.
    
      

Modify project info

PUT /v4/projects/<account>/<project_id>/

    Required parameter (specify at least one):
      name
      description

    Result: "OK"

    Sets user-changeable metadata. Both "name" and "description" are strings;
    the former is used only for looking up project IDs via the
    GET /projects/ methods, and the latter is solely informational.
    
      

Create project

POST /v4/projects/<account>/

    Required parameter:
      name

    Result: {"name": <project name>,
             "project_id": <project ID>,
             "path": <project path>}

    Creates a project with a specified name. Returns errors (as strings) if
    something other than basic authorization goes wrong, e.g., if a project
    with that name already exists.

    The "project_id", an arbitrarily-chosen five-character string, is what gets
    used in other API calls. Note that the name of a project can be changed, as
    it is solely for your own identification purposes, but the project_id is
    used internally and cannot be changed.

    The "path" returned as part of the result is the API path for this project.

    A note about unique naming: you cannot create a project that has the same
    name as an existing project in your account.  Any time an endpoint attempts
    to create a project with a name that already exists, it will append
    " - <n>" for the smallest <n> not already in use.  For instance, the first
    time you try to create a project named "Test", the project will get the
    name "Test"; the second time, the name will be "Test - 1", the third time,
    "Test - 2", and so forth.
    
      

Delete project

DELETE /v4/projects/<account>/<project_id>/

    Result: "Deleted."

    This will irrevocably delete a project and clear all data from it,
    including any jobs that are currently running. No second chances, so only
    call this if you really mean it. Programs that call this API should insert
    their own "Are you sure?" checks.
    
      

Copy project

POST /v4/projects/<account>/<project_id>/copy/

    Optional parameters:
      destination - name for new project
      owner - account that will own new project (defaults to the same account
        that owns the original project)

    Result: {"name": <new project name>,
             "project_id": <new project ID>,
             "path": <new project path>}

    Copies a project with the given ID to a new project. The name that gets
    returned on success is the new project name, either as given in the optional
    "destination" parameter, or by default "Copy of X", where X is the project
    name of the source project. The project_id and path that get returned are
    the randomly-chosen project ID and the path to the project.  See
    POST /projects/<account>/ for more information about project_id and path,
    as well as what happens when creating a project with a name that already
    exists in the system.

    To avoid potential miscopying, copying a project will not work if it has
    jobs currently running.
    
      

Branch project

POST /v4/projects/<account>/<project_id>/project/branch

    Required parameter (specify at least one):
      ids - JSON-encoded list of document IDs
      subsets - JSON-encoded list of subsets

    Optional parameters:
      destination - name for new project

      language, notify, notify_emails - see POST /docs/recalculate/ for details

    Result: {"name": <new project name>,
             "project_id": <new project ID>,
             "path": <new project path>,
             "job_id": <ID# of the processing job>}

    Builds a new project out of the documents with the specified ids and/or the
    documents in the specified subsets.  The new project's name is specified by
    the "destination" parameter, or by default "Branch of X", where X is the
    project name of the source project.  (See POST /projects/<account>/ for
    information on what happens when creating a project with a name that already
    exists in the system.)

    Topics from the original project are copied into the new project.

    Because this endpoint combines the functionality of project creation and
    recalculation, its result contains information about the new project and
    the job ID of the recalculation on the new project.

    Some important notes:

    * This endpoint will check to make sure you have specified either ids or
      subsets (or both), but it will not ensure that the specifications produce
      any documents.  If you supply only document IDs or subsets that do not
      exist in the project, this endpoint will succeed, but the initial job in
      the new project will fail (because there are no documents).

    * If you specify multiple subsets, or subsets and ids, the new project will
      contain the union of what you specify, not the intersection.  That is to
      say, if you use ["male", "20s"] as your subsets, you will get a project
      with all documents marked "male" and all documents marked "20s", and not
      a project with just those documents marked as both "male" and "20s".
    
      

Clear project

POST /v4/projects/<account>/<project_id>/clear/

    Optional parameter:
      remove_uploaded - defaults to true, in which case uploaded documents are
                        removed with everything else; if set to 'false',
                        restores to their just-uploaded state

    Result: "Cleared."

    This will irrevocably clear all data from a project (though the project
    itself will remain, ready for new data); this includes any jobs that are
    currently in the process of adding data. No second chances, so only call
    this if you really mean it. Programs that call this API should insert their
    own "Are you sure?" checks.
    
      

Documents

List document IDs

GET /v4/projects/<account>/<project_id>/docs/ids/

    Optional parameters:
      subset (default "__all__" (entire set of documents))
      uncommitted (boolean) (default false) - if true, will include *only*
        documents that have been added or changed since the last recalculate;
        otherwise, will include *only* versions of documents as of the last
        recalculate

    Result: [<string>, <string>, <string>, ...]

    Lists document IDs in the project.
    
      

Get documents

GET /v4/projects/<account>/<project_id>/docs/

    Optional parameters (specify at most one):
      id - ID of the document to get
      ids - JSON-encoded list of document IDs to get
      limit - number of documents to get, max 25000
    If none of these parameters are specified, defaults to limit = 100.

    Additional options:
      uncommitted (boolean, default false) - if set to true, returns the
        documents that were added or changed since the last recalculate, as
        uploaded; else (by default) returns documents obtained in the last
        recalculate.  If true, ignores "subset" (below).
      doc_fields (JSON-encoded list) - selects fields to include in the
        returned documents.

    Additional options for "limit" mode only:
      offset - number of documents to skip before beginning
      subset - restrict the result to the given subset

    Result: a document dictionary or list of document dictionaries

    Retrieves a document or documents from the database.  A maximum of 25000
    documents will be returned; to retrieve more, use the "offset" parameter to
    request additional batches.  Note also that due to URL length restrictions,
    it is not possible to get more than about 600 documents at a time by ID.

    See http://wiki.services.luminoso.com/documents.html for more information
    about what fields a document contains.
    
      

Add documents

POST /v4/projects/<account>/<project_id>/docs/

    Required: file contents as request body, Content-Type header set to
              "application/json"

    Result: list of objects, in the same order as the uploaded documents;
            these have a "success" key set to either "true" or "false", and...
            - if "true", then the document was successfully stored, and the
              object will have an "_id" key containing the document's _id;
              if there are warnings (see below), it will also have a "warnings"
              key with a list of strings specifying the warnings
            - if "false", then the document had a problem that we could not
              easily accommodate, and it was neither stored nor assigned an
              _id; the object will have a "reason" key whose value is a string
              explaining the reason for the failure

    Takes a JSON-encoded list of dictionaries and stores them until a
    recalculation is performed; until then, they will have no vectors and will
    not be returned as part of document searches, lists of documents, etc. In
    general, this call should be used for the initial upload of documents.

    Returns a list that provides, for each document, either its _id and any
    warnings that may apply, or a reason that the document could not be stored.
    "Warnings" for a document include things like having no text (which is
    allowed, but because not including text may have been a formatting
    accident, we give you a warning) or having an unreadable date (in which
    case we ignore the date, but still accept the document). "Reasons" for
    a document failing include more fundamental errors such as a language
    being specified that we do not support, or including a value of a
    wholly wrong kind (a text string as a prediction key's weight, for
    instance).

    See http://wiki.services.luminoso.com/documents.html for more information
    about what fields an uploaded document may contain, and how they will
    be filled in as defaults, if at all.
    
      

Modify documents

PUT /v4/projects/<account>/<project_id>/docs/

    Required: JSON-encoded dictionary changes as request body, Content-Type
              header set to "application/json"

    Result: "OK"

    Takes a JSON-encoded list of partial (or complete, if you want) document
    dictionaries containing IDs (they must be documents that are already in
    the project, otherwise they will be ignored), and stores the changes.  The
    fields that you can specify are the same as when uploading documents.

    NOTE: This does NOT automatically trigger a rebuild of the project; for
    the changes to take effect, you need to POST to /docs/recalculate/.
    
      

Delete documents

DELETE /v4/projects/<account>/<project_id>/docs/

    Required parameters:
      ids - JSON-encoded list of document IDs to delete

    Result: "OK"

    Marks documents for removal from the database.  Note that due to URL length
    restrictions, it is not possible to delete more than about 600 documents at
    a time.

    NOTE: This does NOT automatically trigger a rebuild of the project; for
    the changes to take effect, you need to POST to /docs/recalculate/.
    
      

Revert uncommitted changes

POST /v4/projects/<account>/<project_id>/docs/revert/

    Result: "OK"

    Removes all uncommitted changes (i.e., additions, removals, or changes of
    documents since the last successful recalculate).
    
      

Recalculate project

POST /v4/projects/<account>/<project_id>/docs/recalculate/

    Optional parameters:
      language - a two-letter language string. You can specify the language on
        each document, but if all of your documents are in, say, French, you
        can specify "language=fr" in this call, instead of having to specify it
        on every document.  For a list of supported languages, check the
        GET /supported_languages/ endpoint.

      notify (boolean) (default false) - if true, sends an email when the
        job has finished (to the user who started the job, unless
        "notify_emails" is specified)

      notify_emails - JSON-encoded list of email addresses to notify when
        the job has finished (if "notify_emails" parameter is specified,
        "notify" parameter is assumed to be true)

    Result: the ID# of the processing job

    Tells the system to take all documents in the database and rebuild all of
    the information about the project. This is generally only necessary after
    the initial document upload, i.e. a POST to /docs/.

    Rebuilding can only be done if there are no other jobs in progress; if
    another job is running, calling this endpoint will return an error.
    
      

Search documents

GET /v4/projects/<account>/<project_id>/docs/search/

    Required parameter (specify at least one):
      text - string of text to search on (see note below)
      topic - ID of topic to search on
      topics - JSON-encoded list of IDs of topics to search on
      terms - JSON-encoded list of terms to search on
        (alternative (deprecated) format: comma-separated string of terms);
        to search for the opposite of a term, prefix it with "~"
      vector - pack64'd vector to search on
      vectors - JSON-encoded list of pack64'd vectors to search on
      negative - JSON-encoded object with any of text/topic/terms/vector,
                 of things to subtract out of search
      zero - JSON-encoded object with any of text/topic/terms/vector,
             of things to zero out of search

    Optional parameters:
      start_at (default 0) - index at which to start returning results
      limit (default 10) - how many results to return (maximum 100)
      (For instance, if "start_at" is 30 and "limit" is 5, this will return
       search results 30 to 34.)
      subset (default "__all__") - subset in which to search for documents
      doc_fields (JSON-encoded list) - selects fields to include in the
        returned documents.

    Result: {"search_vector": <pack64'd search vector>,
             "search_results": <list of [{"document": <document dict>,
                                          "exact_indices": [indices],
                                          "conceptual_indices": [indices]},
                                         <matching strength>] pairs>,
             "num_exact_matches": <# docs that matched exactly>,
             "num_related_matches": <# additional docs related to your query>,
             "exact_terms": <list of terms that count as exact matches>,
             "related_terms": <list of terms that indicate related documents>}

    Get documents that match a search query. The result includes the search
    vector (in case you need to reuse it) and, in "search_results", a list of
    pairs. In each pair, the first item is an object with three keys:

        "document": the full document dictionary.

        "exact_indices": a (possibly empty) list of [start, end] pairs of
            indices into the document's text, indicating the locations of exact
            matches for the search

        "conceptual_indices": the same, but for conceptual matches

    The second item in each pair is the matching strength.

    For "text", the argument is treated as a series of words of which each
    should be matched, though as much as possible the search will try to
    collocate terms out of the query, so that if "baseball mitt" is a phrase
    in your data, searching for the text "baseball mitt good" will search on
    the terms "baseball mitt" and "good" (rather than the three words
    separately).

    More than one of text/topic(s)/terms/vector(s) can be specified; the search
    will happen on the sum of the parts.

    See the topic creation endpoint (POST /topics/) for more information on how
    to use "negative" and "zero".

    exact_terms is the list of terms in the text, terms, or topics that you
    searched for. num_exact_matches is the number of documents that matched any
    of those terms. Each document is only counted once, even if it matches
    multiple search terms.

    related_terms is the top related terms to your search, up to 20;
    num_related_matches is the number of additional documents obtained
    by also searching for those.
    
      

Get subset stats

GET /v4/projects/<account>/<project_id>/subsets/stats/

    Optional parameters (specify at most one):
      subset - name of the subset to get statistics for
      subsets - JSON-encoded list of names of subsets to get statistics for
    If neither parameter is specified, use all the subsets.

    Result:
        [{"subset": <name of subset>,
          "mean": <average vector of documents in subset>,
          "count": <number of documents in subset>},
         ...]

    Returns statistics about the documents in a subset. Note that this only
    includes documents that have vectors.
    
      

Get document vectors

GET /v4/projects/<account>/<project_id>/docs/vectors/

    Required parameter (specify exactly one):
      id - ID of the document to get a vector for
      ids - JSON-encoded list of document IDs to get vectors for
      subset - name of subset to get document vectors from

    Result: {<doc ID>: <pack64'd doc vector>, ...}

    Retrieves the vectors for a particular document or documents.
    
      

Get time buckets

GET /v4/projects/<account>/<project_id>/docs/timebuckets/

    Required parameter:
      interval - bucket size - one of "document", "year", "month",
        "day", or "hour"

    Optional parameters:
      subset (default "__all__" (entire set of documents))
      start_time - earliest time to include (in seconds since the epoch)
      end_time - latest time to include (in seconds since the epoch)

    Result: {"interval": <the interval you specified>,
             "buckets": [{"start": <timestamp in seconds>,
                          "mean": <average vector of documents in bucket>,
                          "count": <number of documents in bucket>},
                          ...]}

    Returns statistics about the documents grouped into buckets of the
    specified size. Empty buckets are not included.
    
      

Vectorize documents

POST /v4/projects/<account>/<project_id>/docs/vectors/

    Required: file contents as request body, Content-Type header set to
              "application/json"

    Result: a list of updated document dictionaries

    Takes a JSON-encoded list of dictionaries (documents) and returns a list of
    "complete" documents including vectors.
    This does *not* save the documents, or add any of their information to the
    project!
    
      

Get document-topic correlations

GET /v4/projects/<account>/<project_id>/docs/correlations/

    Result: {<doc ID 1>: {<topic ID 1>: <correlation between doc 1 and topic 1>,
                          <topic ID 2>: ...},
             <doc ID 2>: ...}

    Returns correlations of all documents with all topics.
    
      

Jobs

List jobs

GET /v4/projects/<account>/<project_id>/jobs/

    Optional parameter:
      verbose (default false)

    Result: list of jobs

    By default, returns a list of numbers of currently-running jobs. If the
    optional "verbose" parameter is set to true, returns a list of
    job-status dictionaries for all jobs, past and present.

    Note that in either case, the list may be empty.
    
      

Get job

GET /v4/projects/<account>/<project_id>/jobs/id/<number>/

    Result: {"start_time": <number>,
             "stop_time": <number or null>,
             "source_type": <string>,
             "success": <boolean>}

    Get the status of a job, given its job number. Times are given in number
    of seconds since the epoch. If the job is still running, "stop_time" will
    be null instead of a number. "success" indicates whether the job stopped
    normally or whether something crashed while running.
    
      

Topics

List topics

GET /v4/projects/<account>/<project_id>/topics/

    Optional parameter:
      name_only (default false)

    Result: [<topic dict>, <topic dict>, <topic dict>, ...]

    Gives a list of all topic dictionaries in the project, whose keys are
    "_id", "color", "name", "text", and "vector". The list is ordered by topic
    order (which can be specified; see POST /topics/ and PUT /topics/order/).

    If "name_only" is set to true, the dictionaries will consist only of _id
    and name. (Note that _ids are arbitrary and guaranteed to be unique; names
    are not.)
    
      

Modify topic order

PUT /v4/projects/<account>/<project_id>/topics/order/

    Required parameter:
      order - a JSON-encoded list of topic ids

    Result: new topic order (ordered list of topic ids)

    Sets the given list as the new order for topics. Existing topics not
    included in the list will be reordered to the end.
    
      

Get topic

GET /v4/projects/<account>/<project_id>/topics/id/<topic_id>/

    Result: a topic dictionary

    Topic dictionaries have the form:
         {"_id": <internal ID>,
          "name": <name>,
          "text": <text defining the topic>,
          "color": <HTML color code>,
          "vector": <pack64'd vector>}
    and optionally "negative" and "zero" (see the topic creation endpoint for
    more information).

    If the specified topic does not exist, the result is null.
    
      

Modify topic

PUT /v4/projects/<account>/<project_id>/topics/id/<topic_id>/

    Optional parameters: (same as POST /<project_id>/topics/)

    Result: a topic dictionary (see GET /topics/id/<topic_id>/)

    Changes the details of a topic in the project, using the same parameters as
    when creating a topic. Note, too, that this requires the full dictionary
    and not just the items that are changing.
    
      

Create topic

POST /v4/projects/<account>/<project_id>/topics/

    Optional parameters:
      name (default "New Topic")
      color (default "#808080") - topic's HTML color
      text (default "") - text that defines the topic
      position (default 0, i.e. first on the list)
      negative (no default) - see below
      zero (no default) - see below

    Result: a topic dictionary

    Result will be a JSON object with the keys and values as set above
    (or as filled in via default values) (excluding "position), plus "_id"
    specifying the internal topic ID, and, if applicable, "vector" specifying
    the topic's vector.

    "negative" or "zero" may also be specified, as JSON-encoded object with
    the key "text". "negative" provides text that should be considered as an
    opposite of the text used to define the topic; "zero" provides text that
    should be considered irrelevant to the topic. These can help fine-tune
    your topics. Some examples:

    * text = "good exciting"; negative = {"text": "bad boring"}

      This will set up "good" and "bad" as opposing concepts. Documents related
      to the words "good" and "exciting" will have a high positive correlation
      to this topic; documents related to "bad" and "boring" will have a high
      negative correlation.

    * text = "lions"; zero = {"text": "tigers"}

      Suppose your project has found that people discuss lions and tigers in
      similar ways, and you want to set up a topic about lions, but don't want
      discussions of tigers to accidentally get pulled in. Specifying "tigers"
      as negative would put the two ideas into strict opposition: documents
      that are less about tigers would be considered to be more about
      lions. Instead, put "tigers" as the text for "zero": documents about
      lions will have a high correlation regardless of their keyboard content,
      and documents about tigers will have a low (i.e., near zero, rather than
      negative) correlation with the topic.
    
      

Delete topic

DELETE /v4/projects/<account>/<project_id>/topics/id/<topic_id>/

    Result: {"deleted": topic_id} if successfully deleted, or
            {"not_found": topic_id} if not found.

    Deletes a topic from the project.
    
      

Get topic stats

GET /v4/projects/<account>/<project_id>/topics/stats/

    Optional parameter:
      subset (default "__all__" (entire set of documents))

    Result: {".all": {"consistency": <consistency>},
             <topic_id>: {"correlation": <dict>,
                          "distance": <float>,
                          "name": <string>},
             ...}

    Gives an object for each topic that maps its topic ID to an object with the
    topic's correlation, distance, and name. "correlation" is a dictionary that
    includes "mean", "stdev", "stderr", "n", and "Zscore". "distance" is the
    number of standard deviations that the topic is from the mean document.

    Also gives, in an ".all" object, the "consistency" of the documents,
    indicating how similar they are to one another.
    
      

Get topic-document correlation histograms

GET /v4/projects/<account>/<project_id>/topics/histograms/

    Optional parameter:
      bins (default 10)

    Result: {<topic ID>: [<list of bin sizes>, <list of bin borders>], ...}

    Get a dictionary mapping each topic to histogram information for that
    topic. The information is in two lists: first, the number of documents in
    each bin, and second, the endpoints for the bins.
    
      

Get topic correlation to text

PUT /v4/projects/<account>/<project_id>/topics/text_correlation/

    Required parameter (specify exactly one):
      text - string to correlate to topics
      texts - JSON-encoded list of strings to correlate to topics

    Result: for text: {<topic id>: <correlation>, ...}
            for texts: list of results for each text

    Given text or texts to match, return the correlation with each of the
    topics.
    
      

Get topic-topic correlations

GET /v4/projects/<account>/<project_id>/topics/correlation/

    NOTE: By default this yields a CSV file. It can also be set to yield an
    XLSX file or a JSON object.

    Optional parameters:
      format (default "csv") - one of "csv", "json", or "xlsx". Specifies the
        format of the returned data.
      [deprecated] use_json (default false) - ONLY CONSIDERED IF NO VALUE
        SUPPLIED FOR THE format PARAMETER. If true, return JSON. If false,
        return CSV.

    Result:
      JSON version: {<topic ID 1>: {<topic ID 1>: <number>,
                                    <topic ID 2>: <number>,
                                    ...},
                     ...}

      CSV version: A CSV file in which the rows and columns are topics and
        the entries are correlation values between the topics.

      XLSX version: An XLSX file with three worksheets. In one formatted
        worksheet, the rows and columns are topics and the entries are
        correlation values between the topics. Topic names are bolded and %
        values have a 3-color-scale. Another worksheet has a series of bar
        charts based on each of the rows of the first sheet. The final
        worksheet has unformatted data rows from the first worksheet, each of
        which is sorted in increasing order.

    Returns the correlations of each topic with each other topic.
    
      

Get topic-subset correlations

GET /v4/projects/<account>/<project_id>/topics/subset_correlation/

    NOTE: By default this yields a CSV file. It can also be set to yield an
    XLSX file or a JSON object.

    Optional parameters:
      format (default "csv") - one of "csv", "json", or "xlsx". Specifies the
        format of the returned data.
      [deprecated] use_json (default false) - ONLY CONSIDERED IF NO VALUE
        SUPPLIED FOR THE format PARAMETER. If true, return JSON. If false,
        return CSV.

    Result:
      JSON version: {<subset 1>: {<topic ID 1>: <number>,
                                  <topic ID 2>: <number>,
                                  ...},
                     ...}

      CSV version: A CSV file in which the rows are subsets, the columns are
        topics, and the entries are correlation values between the subsets and
        the topics.

      XLSX version: A formatted XLSX file with one worksheet in which the rows
        are subsets, the columns are topics, and the entries are correlation
        values between the subsets and the topics. Topic names and subset names
        are in bold while % values have a standard 3-color-scale conditional
        formatting.

    Returns the correlations of each topic with each subset.
    
      

Get topic timeline correlations

GET /v4/projects/<account>/<project_id>/topics/timeline_correlation/

    NOTE: By default this yields a CSV file. It can also be set to yield an
    XLSX file or a JSON object.

    Optional parameters:
      subsets (default ["__all__"]) - jsonified list of subsets to count
        documents in. Cannot contain more than one subset unless format is
        specified as "xlsx".
      [deprecated] subset (default "__all__") - subset to count documents in.
        ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE subsets PARAMETER.
      interval (default "document") - one of "document", "year", "month",
        "day", or "hour"
      format (default "csv") - one of "csv", "json", or "xlsx". Specifies the
        format of the returned data.
      [deprecated] use_json (default false) - ONLY CONSIDERED IF NO VALUE
        SUPPLIED FOR THE format PARAMETER. If true, return JSON. If false,
        return CSV.

    Result:
      JSON version: [{"start": <start time of bucket>,
                      "count": <number of documents in bucket>,
                      "correlations": {<topic ID 1>: <number>,
                                       <topic ID 2>: <number>,
                                       ...}},
                     ...]

      CSV version: A CSV file in which the rows are time buckets, the columns
        are topics, and the entries are correlation values between the
        average document in each time bucket and the topics.

      XLSX version: A formatted XLSX file with one worksheet per requested
        subset. In each worksheet, the rows are time buckets, the columns are
        topics, and the entries are correlation values between the average
        document in each time bucket and the topics. Topic names are in bold
        while % values have a standard 3-color-scale conditional formatting.

    Returns the correlations of the documents to each topic at each point in
    time.
    
      

Get topic document-counts

GET /v4/projects/<account>/<project_id>/topics/doc_counts/

    NOTE: By default this yields a CSV file. It can also be set to yield an
    XLSX file or a JSON object.

    Optional parameters:
      ids (default all topics) - list of topic IDs to include
      subsets (default ["__all__"]) - jsonified list of subsets to count
        documents in. Cannot contain more than one subset unless format is
        specified as "xlsx".
      [deprecated] subset (default "__all__") - subset to count documents in.
        ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE subsets PARAMETER.
      format (no default) - one of "csv", "json", or "xlsx". Specifies the
        format of the returned data.
      [deprecated] use_json (default false) - ONLY CONSIDERED IF NO VALUE
        SUPPLIED FOR THE format PARAMETER. If true, return JSON. If false,
        return CSV.

    Returns, for each topic, the number of exact-match documents and the
    number of related-match documents.  These are the same numbers that
    are included along with search results (from /docs/search/).
    
      

Terms

List terms

GET /v4/projects/<account>/<project_id>/terms/

    Optional parameters:
      limit (default 10, max 50000) - number of terms to return
      subset (default "__all__") - subset from which to get terms
      terms - JSON-encoded list of terms, to get information for instead of
              the top terms

    Result: [{"term": <term>,
              "text": <most common surface text>,
              "all_texts": {<text>: <frequency> for all texts that correspond
                            to the term},
              "vector": <pack64'd vector>,
              "score": <relevance score>,
              "distinct_doc_count": <number of documents containing term>,
              "bg_freq": <approximate frequency of term in background corpus>},
             ...]

    Gives a dictionary for each of the top N terms in the project,
    or for the terms that you specify. If you specify terms, any that
    do not actually exist will be ignored.
    
      

Ignore a term

PUT /v4/projects/<account>/<project_id>/terms/ignorelist/

    Required parameter:
      term (string) - term to ignore

    Optional parameter:
      substring (boolean) (default false)

    Result: "OK"

    Tells the relevance calculator to ignore a particular term. Useful for
    hiding obscenity, "RT", or other meaningless terms that are overwhelming
    the data.

    If "substring" is false, only the exact term will be ignored. If
    "substring" is true, anything containing the term as a substring will be
    ignored. (This is useful for, say, telling it to ignore a certain
    four-letter word starting with F, and having it thereby ignore F, F-ing,
    F-ed, motherF-er, etc. It's not a good idea to ignore any term that
    contains "rt" as a substring.)

    Note that if substring is false, the string being ignored is a *term*, not
    the pre-stemmed original text that might appear in a visualization.  If
    "RT" is dominating the wordmap, use the underlying term, which is probably
    "rt|en".
    
      

Unignore a term

DELETE /v4/projects/<account>/<project_id>/terms/ignorelist/

    Required parameter:
      term (string) - term to unignore

    Optional parameter:
      substring (boolean) (default false)

    Result: "OK" or "Not Found"

    Tells the relevance calculator to stop ignoring a particular term.
    
      

List ignored terms

GET /v4/projects/<account>/<project_id>/terms/ignorelist/

    Result: {"substring": [...], "fullstring": [...]}

    Gets the list of terms being ignored, both the "substring" list and the
    "fullstring" list.
    
      

Restem a term

PUT /v4/projects/<account>/<project_id>/terms/restem/

    Required parameters:
      from_term (string) - term to store differently
      to_term (string) - term to store it as instead

    Result: "OK"

    Instructs future recalculations to treat occurences of "from_term" as if
    they are actually "to_term".  Note that this will have no effect until the
    project is recalculated (though it may cause some oddities in searches).

    Natural language processing is imperfect, and sometimes it fails to combine
    different forms of the same word, particularly if that word is unfamiliar.
    If your project is about the Zooty Awards, aka the Zooties, the module that
    processes text likely won't realize that "Zooties" is a form of "Zooty",
    and will represent them as "zooties|en" and "zooty|en", respectively.  If
    that happens, you can use this endpoint to tell the module that, in the
    future, when it decides that a word's stemed form is "zooties|en", it
    should use "zooty|en" instead.

    Note that both "from_term" and "to_term" are stemmed forms, not surface
    forms: they're the lowercase forms with language tags like "|en" on them.
    
      

Remove a restem

DELETE /v4/projects/<account>/<project_id>/terms/restem/

    Required parameter:
      from_term (string) - term to stop storing differently

    Result: "OK"

    Removes restem information for "from_term", so that future recalculations
    will go back to treating the term as an independent form.
    
      

List restems

GET /v4/projects/<account>/<project_id>/terms/restem/

    Result: {"from_term": "to_term", ...}

    Shows all the restem information for the project.
    
      

Search terms

GET /v4/projects/<account>/<project_id>/terms/search/

    Required parameter (specify at least one):
      text
      topic
      topics
      terms
      vector
      vectors
      negative
      zero

    Optional parameters:
      limit (default 10)
      domain (default true) - if false, results can include not just the terms
                              that appear in the project, but also terms
                              from the background space
      subset (default "__all__") - subset from which to get terms
                                   (if domain is true)

    Result: {"search_vector": <pack64'd search vector>,
             "search_results": <list of [term-dict, matching-strength] pairs>}

    Given text, a topic, terms, or a vector, returns the search vector (in case
    you need to reuse it) and a list of pairs for the terms most correlated
    with it. The first item in each pair is the full term dictionary, as in
    GET /terms/, and the second is the matching strength of that term.

    As with GET /docs/search/, if more than one of text, topic(s), terms, and
    vector(s) is specified, the search will happen on the sum of the
    parts. (See the documentation on that call for more information on the
    formatting of "text", "topic", "terms", "vector", "negative", and "zero".)
    
      

Get term document-counts

GET /v4/projects/<account>/<project_id>/terms/doc_counts/

    NOTE: By default this yields a CSV file. It can also be set to yield an
    XLSX file or a JSON object.

    Optional parameters:
      terms (default the top terms) - list of terms to include
      limit (default 100) - number of terms to include
      subsets (default ["__all__"]) - jsonified list of subsets to count
        documents in. Cannot contain more than one subset unless format is
        specified as "xlsx".
      [deprecated] subset (default "__all__") - subset to count documents in.
        ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE subsets PARAMETER.
      format (default "csv") - one of "csv", "json", or "xlsx". Specifies the
        format of the returned data.
      [deprecated] use_json (default false) - ONLY CONSIDERED IF NO VALUE
        SUPPLIED FOR THE format PARAMETER. If true, return JSON. If false,
        return CSV.

    Returns, for each term, the number of exact-match documents and the
    number of related-match documents.  These are the same numbers that
    are included along with search results (from /docs/search/).
    
      

Prediction

Train predictor

POST /v4/projects/<account>/<project_id>/prediction/train/

    Optional parameters:
      regressors (JSON-encoded list of strings) - list of names of target
        variables that should use regressors instead of classifiers (see below
        for details)
      classifiers (JSON-encoded list of strings) - list of names of target
        variables that should use classifiers instead of regressors (see below
        for details)

    Result: the ID# of the predictor-training job

    Trains a predictor for each of the target variables from the "predict"
    fields of all documents in the project.  The predictors can then be used to
    predict categories or numerical values for documents using the
    GET /prediction/ endpoint.

    By default, target variables whose values are numerical will be used to
    train regressors, and target variables whose values are strings will be
    used to train classifiers.  For example, if your project contains two
    documents, whose "predict" fields are
    {"rating": {"value": 2, "weight": 1.0}} and
    {"rating": {"value": 3, "weight": 1.0}},
    then the predicted "rating" for a new document could be some other number
    such as 2.2, whereas if the two documents' "predict" fields are
    {"rating": {"value": "2", "weight": 1.0}} and
    {"rating": {"value": "3", "weight": 1.0}},
    the predicted "rating" for a new document will always be either "2" or "3".
    If the "rating" were a number on some documents and a string on others,
    then it would be treated as numbers (and use a regressor) if all the
    strings could be turned into numbers, otherwise it would be treated as
    strings (and use a classifier).

    You can override the default behavior using the "regressors" and/or
    "classifiers" parameters to this API call: passing ["rating"] as the
    "regressors" parameter will cause the "2" and "3" to be treated as if they
    were 2 and 3, and passing it as the "classifiers" parameter will cause the
    2 and 3 to be treated as if they were "2" and "3".

    For more information about the format of the "predict" field, refer to
    http://wiki.services.luminoso.com/documents.html .
    
      

Predict

POST /v4/projects/<account>/<project_id>/prediction/

    Required: file contents as request body, Content-Type header set to
              "application/json"

    Result: [{<target variable>: <value>, ...}, ...]

    Takes a JSON-encoded list of document dictionaries and computes their
    predicted values using any predictors that have been built (see the
    POST /prediction/train/ endpoint).  The documents do not need to be
    complete, but if they do include vectors, those vectors will be used
    instead of being recomputed from the text.

    Returns a list of predicted values, one dictionary for each document, in
    the same order as the documents.  Each dictionary has a value for
    each target variable that is listed in the "predict" field on any documents
    that the predictors were trained on.

    This does NOT save the documents or add any of their information to the
    project.
    
      

Users

Log in

POST /v4/user/login/

    Required parameters:
      username
      password

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

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

    Logs in a user. For more information, see:
         http://wiki.services.luminoso.com/how-to-write-an-api-client.html
    
      

Log out

POST /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 /v4/user/profile/

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

Modify user (self)

PUT /v4/user/profile/

    Optional parameters (must supply at least one):
      full_name
      default_account

    Result: "User updated."

    Updates your user information.
    
      

Recover password

GET /v4/user/password/

    Required parameter:
      email - 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.
    
      

Reset password

POST /v4/user/password/

    Required parameters:
        email (string) - the email address of the user
        expiration (int) - the expiration time from the emailed url
        signature (string) - the signature from the emailed url
        password (string) - the new password (see
          http://wiki.services.luminoso.com/passwords.html for requirements)

    Result: "Password set."

    This endpoint is to be posted to by the webform that you get to
    by clicking the link in a password-recovery email.
    
      

Change password

PUT /v4/user/password/

    Required parameters:
      old_password
      new_password (see http://wiki.services.luminoso.com/passwords.html for
        requirements)

    Result: "Password changed."

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

Accounts

List accounts

GET /v4/accounts/

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

    Result: {"accounts": [{"account_id": <account ID 1>,
                           "account_name": <name of account 1>,
                           "permissions": <permissions on account 1>},
                          {"account_id": <account ID 2>,
                           "account_name": <name of account 2>,
                           "permissions": <permissions on account 2>},
                          ... ],
             "default_account": <ID of default account>}

    Returns the account IDs of the accounts for which the logged-in user
    has the specified permission.
    
      

Get account info

GET /v4/accounts/<account>/

    Result: {"account_name": <account name>,
             "email": <account email address>,
             "billing_plan": <name of current billing plan>}

    Get info about the account.
    
      

Get credit card info

GET /v4/accounts/<account>/credit_card/

    Result: {"can_pay_by_card": <boolean>,
             "card": {"type": <type of credit card (e.g. Visa)>,
                      "expiration": [<year>, <month>],
                      "last4": <last 4 digits of credit card number (string)>}}

    Get credit card information.
    If there is no card on file, the "card" field will be null.
    
      

Delete credit card

DELETE /v4/accounts/<account>/credit_card/

    Result: "Deleted."

    Delete credit card information.
    
      

Modify account info

PUT /v4/accounts/<account>/

    Optional parameters (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.
    
      

Invite user to account

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

    Required parameters:
      email - email address to invite
      permissions - JSON-encoded list of permissions to give user on account

    Optional parameters:
      expiration_days (default 7) - number of days until invitation expires

    Result: "Email sent."

    Invites a user to join your account, by sending him an email.
    If the user does not yet have a Luminoso login, he 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 he uses for his login.
    
      

Join account

POST /v4/accounts/<account>/join/

    Required parameters:
      email (string) - username of user who's joining
      permissions (list) - list of permissions user will have on account
      expiration (int) - the expiration time from the invite url
      signature (string) - the signature from the invite url

    Result: "Joined account."

    Joins the specified user to the account. This means that the admins
    of that account will be able to see that the user exists, and will
    be able to modify the user's permissions on that account.  You can
    only do this if you have received an invitation from an admin of the
    account.
    
      

Create user

POST /v4/accounts/<account>/users/

    Required parameters:
      email (string)
      full_name (string)
      password (string) (see http://wiki.services.luminoso.com/passwords.html
        for password requirements)
      permissions (list) - list of permissions user will have on account
      expiration (int) - the expiration time from the invite url
      signature (string) - the signature from the invite url

    Result: 'User created.'

    Creates a new user owned by the account.
    
      

Delete user

DELETE /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 /v4/accounts/<account>/users/<email>/profile/

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

    Gets information about the specified user.

    Requires that you have manage permissions on the specified account and it
    owns the user.
    
      

Modify user

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

    Optional parameters (must supply at least one):
      full_name
      default_account

    Result: "User updated."

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

List users

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

    Result: {"owners": {<email of owner>: <list of permissions>}
             "members": {<email of user 1>: <list of permissions>,
                         <email of user 2>: <list of permissions>,
                         ...},
             "guests": {<email of user 3>: <list of permissions>,
                        <email of user 4>: <list of permissions>,
                        ...}}

    Gets the permissions on this account for all users who have permissions
    through 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. "Owners" are the owners of this account (generally
    whoever created it); there will always be either one or zero owners.

    Note also that there could be other users who have access to your
    account's projects through a different account (e.g., the Luminoso
    staff can access everything), and these users will not be included in
    the results.
    
      

Modify user permissions

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

    Required parameters:
      permissions - JSON-encoded list of permissions

    Optional parameters:
      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 his
    permissions on the account; in that case you should delete the user
    instead.
    
      

Get billing plan

GET /v4/accounts/<account>/plan/

    Optional parameter:
      billing_period - a [<year>, <month>] tuple;
        defaults to the current billing period
        (for example, July 2013 would be [2013, 7])

    Result: Information about current billing plan:
      {"name": <plan name>,
       "price": <price per billing period in cents>
       "call_limits": {"regular": <number>, "big": <number>, ...},
       "space_limit": <number of bytes>,
       "call_penalties": {"regular": <penalty per extra call in cents>, ...},
       "space_penalty": <penalty per extra byte in cents>}
    
      

Set billing plan

POST /v4/accounts/<account>/plan/

    Required parameter:
      plan - name of new plan

    Optional parameter:
      start_period - a [<year>, <month>] tuple;
        defaults to the *next* complete billing period (not the current one)

    Result:
       {"name": <plan name>,
        "price": <price per billing period in cents>
        "call_limits": {"regular": <number>, "big": <number>, ...},
        "space_limit": <number of bytes>,
        "call_penalties": {"regular": <penalty per extra call in cents>, ...},
        "space_penalty": <penalty per extra byte in cents>}

    Sets the billing plan for this account.
    (This will automatically unsubscribe the account from any other
     billing plan, because a given account may only be on one plan.)
    Returns information about the new billing plan.
    
      

Get usage report

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

    Optional parameter:
      billing_period - a [<year>, <month>] tuple;
        defaults to the current billing period
        (for example, July 2013 would be [2013, 7])

    Result:
      {"call_counts": {"regular": <number>, "big": <number>, ...}
       "total_space": {"total": <number of bytes currently used>,
                       "max": <max bytes used this billing period>
                       "timestamp": <last update time, in seconds>}
      "project_space":
        {<project ID>:
           "space": <number of bytes used by this project>,
           "timestamp": <last update time, in seconds>,
         ...}}

    Returns usage information for the specified billing period.
    
      

Tokens

List tokens

GET /v4/user/tokens/

    Result: list of token dictionaries (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.
    
      

Get token

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

    Result: {"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.)
    
      

Create token

POST /v4/user/tokens/

    Result: a token dictionary (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.
    
      

Delete token

DELETE /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 to the dashboard, that dashboard 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.
    
      

Other

List supported languages

GET /v4/supported_languages/

    Result: list of supported languages (as [code, readable name] pairs)
    
      

Ping

GET/PUT/POST/DELETE /v4/ping/

    Result: "pong"

    This method does nothing. Therefore, it may be useful to test your
    connection to the API or to keep it alive.
    
      

Get version identifier

GET /v4/version/

    Result: version identifier (as a string)