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.


  

Projects

List projects

GET /api/v4/projects/

    Optional parameters:
      name (string)
          return only projects with a specified name (useful if you know the
          name but forget the project ID)
      fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include on each returned object

    Result:
      an array of metadata objects

    Returns the 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 /api/v4/projects/<account>/

    Optional parameters:
      name (string)
          return only projects with a specified name (useful if you know the
          name but forget the project ID)
      fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include on each returned object

    Result:
      an array of metadata objects

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

Create project

POST /api/v4/projects/<account>/

    Required parameter:
      name (string)
          name of the project to create

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

    Tabulation:
      increases "projects created" by one

    Creates a project with a specified name.

    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.
    
      

Copy project

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

    Optional parameters:
      destination (string, defaults to "Copy of [original project name]")
          name for new project
      owner (string, defaults to account that owns the original project)
          account that will own new project

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

    Tabulation:
      increases "projects created" by one (does not affect documents/text)

    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 /api/v4/projects/<account>/<project_id>/project/branch/

    Required parameter (specify at least one):
      ids (JSON-encoded array of strings)
          an array of document IDs
      subsets (JSON-encoded array of strings)
          an array of subset names

    Optional parameters:
      destination (string, defaults to "Branch of [original project name]")
          name for new project
      language
      notify
      notify_emails
          see POST /docs/recalculate/ for details of these three options

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

    Tabulation:
      increases "projects created" by one; increases "documents uploaded" and
      "text uploaded" based on the documents in the new project

    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".
    
      

Delete project

DELETE /api/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.
    
      

Get project info

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

    Optional parameter:
      fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include on the returned object

    Result:
      a metadata object:

        {"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 /api/v4/projects/<account>/<project_id>/

    Required parameter (specify at least one):
      name (string)
          new name for the project
      description (string)
          new description for the project

    Result:
      "OK"

    Sets user-changeable metadata.  "name" is used only for looking up project
    IDs via the GET /projects/ methods; "description" is solely informational.
    
      

Clear project

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

    Optional parameter:
      remove_uploaded (boolean, default true)
          if true, uploaded documents are removed with everything else; if
          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

Get documents

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

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

    Additional optional parameters:
      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 array of strings, defaults to all fields)
          which fields to include in the returned documents

    Additional optional parameters for "limit" mode only:
      offset (integer, default 0)
          number of documents to skip before beginning
      subset (string, defaults to all documents)
          restrict the result to the given subset

    Result:
      a document object or array of document objects

    Retrieves a document or documents from the database.  A maximum of 25000
    documents can 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://support.luminoso.com/customer/portal/articles/1936096 for more
    information about what fields a document contains.
    
      

Add documents

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

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

    Result:
      an array 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 an array
        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

    Tabulation:
      increases "documents uploaded" and "text uploaded"

    Takes a JSON-encoded array of document objects 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 an array 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://support.luminoso.com/customer/portal/articles/1936096 for more
    information about what fields an uploaded document may contain, and what
    default values they receive, if any.
    
      

Recalculate project

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

    Optional parameters:
      language (string, defaults to project's language, or "en" if none)
          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.  If this is specified, it will override any
          language specified on the documents.  For a list of supported
          languages, check the GET /supported_languages/ endpoint.
      notify (boolean, default false unless "notify_emails" is specified)
          if true, sends an email when the job has finished (to the addresses
          specified in "notify_emails", or to the user who started the job by
          default)
      notify_emails (JSON-encoded array of strings)
          an array of email addresses to notify when the job has finished (if
          "notify_emails" parameter is specified, "notify" parameter is assumed
          to be true; defaults to the user who started the job if "notify" is
          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.
    
      

Delete documents

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

    Required parameter:
      ids (JSON-encoded array of strings)
         an array 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/.
    
      

Modify documents

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

    Required:
      JSON-encoded array of document objects changes as request body,
      Content-Type header set to "application/json"

    Result:
      "OK"

    Tabulation:
      increases "documents uploaded" by one for each document changed;
      increases "text uploaded" if document texts are included

    Takes a JSON-encoded array of partial (or complete, if you want) document
    objects 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/.
    
      

Revert uncommitted changes

POST /api/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).
    
      

List document IDs

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

    Optional parameters:
      subset (string, defaults to all documents)
          subset for which to get the document IDs
      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:
      an array of document ID strings

    Lists document IDs in the project.
    
      

Search documents

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

    Required parameter (specify at least one):
      text (string)
          string of text to search on (see note below)
      topic (string)
          ID of topic to search on
      topics (JSON-encoded array of strings)
          array of IDs of topics to search on
      terms (JSON-encoded array of strings)
          array of terms to search on
      vector (string)
          pack64'd vector to search on
      vectors (JSON-encoded array of strings)
          array of pack64'd vectors to search on
      negative (JSON-encoded object)
          object with any of text/topic/terms/vector as keys, of things to
          subtract out of search
      zero (JSON-encoded object)
          object with any of text/topic/terms/vector as keys, of things to zero
          out of search

    Optional parameters:
      start_at (integer, default 0)
          number of documents to skip before beginning
      limit (integer, default 10, maximum 20000)
          how many results to return.  For instance, if "start_at" is 30 and
          "limit" is 5, this will return search results 30 to 34.
      subset (string, defaults to all documents)
          restrict the result to the given subset
      doc_fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include in the returned documents
      format (string, default "json")
          specifies the format in which to return the data.  Valid formats are
          "json, "csv", and "xlsx".  If "csv" or "xlsx", the returned
          spreadsheet contains a header row with the values
              [Text, Exact Match, Conceptual Match, Date, Title, URL, Subset]
          plus as many additional "Subset" headings as are necessary.  If
          "json", return format is a JSON-encoded object, described below.
      exact_only (boolean, default false)
          if true, return only documents with exact matches to the search; if
          false, return conceptual matches as well

    Result:
      {"search_vector": <pack64'd search vector>,
       "search_results": <array of [{"document": <document object>,
                                     "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": <array of terms that count as exact matches>,
       "related_terms": <array 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", an array of
    pairs.  In each pair, the first item is an object with three keys:

      document
          the full document object
      exact_indices
          a (possibly empty) array 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 list of top related terms to your search, up to 20;
    num_related_matches is the number of additional documents obtained
    by also searching for those.
    
      

Tag documents by topic

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

    Optional parameters:
      topic_ids (JSON-encoded array of strings, defaults to all topics)
          consider only the specified topics
      tagged_only (boolean, default false)
          return only documents with at least one tag
      subset (string, defaults to all documents)
          restrict the result to the given subset
      limit (integer, default 25000, maximum 25000)
          number of documents to return
      offset (integer, default 0)
          number of documents to skip before beginning
      doc_fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include in the returned documents

    Result:
      {"documents": <array of document objects, each with the additional "tags"
                     key containing an array of topic IDs>,
       "topics": <array of objects describing the topics that were considered;
                  see GET /topics/, but note that these objects lack the
                  'vector' key>}

    Get the documents in the project, tagged with the topics they match.  See
    also GET /docs/search/ and GET /topics/doc_counts/, which use the same
    criteria for document matching; and PUT /topics/text_tags/, which tags text
    that is not part of the project.
    
      

Get subset stats

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

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

    Result:
      an array of objects, each of the form

        {"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.
    
      

Get document vectors

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

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

    Result:
      an object mapping document IDs to pack64'd doc vectors

    Retrieves the vectors for a particular document or documents.
    
      

Vectorize documents

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

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

    Result:
      an array of updated document objects

    Tabulation:
      increases "documents uploaded" and "text uploaded"

    Takes a JSON-encoded array of document objects and returns an array 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 /api/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.
    
      

Get time buckets

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

    Required parameter:
      interval (string)
          one of "year", "quarter", "month", "week", "day", "hour", or
          "document"

    Optional parameters:
      subset (string, defaults to all documents)
          subset in which to look for documents
      start_time (integer)
          earliest time to include (in seconds since the epoch)
      end_time (integer)
          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.
    
      

Jobs

List jobs

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

    Optional parameter:
      verbose (boolean, default false)
          if false, returns an array of numbers of currently-running jobs; if
          true, returns an array of job status objects for all jobs, past and
          present

    Result:
      an array of job numbers or job status objects

    Returns job numbers or job status objects, as described above.  (Note that
    in either case, the array may be empty.)
    
      

Get job

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

    Result:
      a job status object:

        {"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 /api/v4/projects/<account>/<project_id>/topics/

    Optional parameter:
      name_only (boolean, default false)
          if true, topic dicts will have only "_id" and "name" keys.  (Note
          that IDs are arbitrary and guaranteed to be unique; names are not.)

    Result:
      an array of topic dictionaries

    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/).
    
      

Create topic

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

    Required parameter:
      text (string)
          text that defines the topic (cannot be empty)

    Optional parameters:
      name (string, default "New Topic")
          name for the topic
      color (string, default "#808080")
          topic's HTML color
      position (integer, default 0)
          position in which to order the topic (0 = first)
      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
    (excluding "position"), or as filled in via default values, 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 tiger content,
      and documents about tigers will have a low (i.e., near zero, rather than
      negative) correlation with the topic.
    
      

Modify topic order

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

    Required parameter:
      order (JSON-encoded array of strings)
          the topic IDs, in their desired order

    Result:
      an array of all topic IDs in their new order

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

Delete topic

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

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

    Deletes a topic from the project.
    
      

Get topic

GET /api/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 POST /topics/ for more
    information).

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

Modify topic

PUT /api/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>/)

    Replaces a topic with a new one (generally a modified version of the old
    one).  Note that this requires the full dictionary and not just the items
    that are changing; if items are left out, they will be set to the same
    defaults as when creating a topic, not to the values they had before.
    
      

Get topic correlation to text

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

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

    Result:
      for text: an object mapping topic IDs to correlations
      for texts: an array of such objects, one for each text

    Tabulation:
      Increases "documents uploaded" and "text uploaded"

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

Tag text with matching topics

PUT /api/v4/projects/<account>/<project_id>/topics/text_tags/

    Required parameter:
      texts (JSON-encoded array of strings)

    Optional parameter:
      topic_ids (JSON-encoded array of strings, defaults to all topics)
          consider only the specified topics

    Result:
      {"texts": <array of objects with "text" and "tags" keys>,
       "topics": <array of objects describing the topics that were considered;
                  see GET /topics/, but note that these objects lack the
                  'vector' key>}

    Tabulation:
      Increases "documents uploaded" and "text uploaded"

    Given texts, mark each with the IDs of the topics they match.  See also
    GET /docs/search/ and GET /topics/doc_counts/, which use the same criteria
    for document matching; and GET /docs/tag/, which tags documents that are
    already part of the project.
    
      

Get topic stats

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

    Optional parameter:
      subset (string, defaults to all 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-counts

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

    Optional parameters:
      ids (JSON-encoded array of strings, defaults to all topics)
          which topic IDs to include
      subsets (JSON-encoded array of strings, defaults to all documents)
          which subsets to count documents in.  Cannot contain more than one
          subset unless format is specified as "xlsx".
      [deprecated] subset (string, defaults to all documents)
          subset to count documents in
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE subsets PARAMETER.
      format (string, default "csv" if deprecated use_json is not specified)
          one of "csv", "json", or "xlsx"; specifies the format of the returned
          data
      [deprecated] use_json (boolean, default false)
          if true, return JSON; if false, return CSV
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE format PARAMETER.

    Result:
      JSON version:
        {<topic_id>: {"num_exact_matches": <number of docs>,
                      "num_related_matches": <number of docs>},
         ...}

      CSV version:
        A CSV file in which the rows are topics and their
        exact/conceptual/total match numbers and percentages.

      XLSX version:
        An XLSX file with two sheets per subset requested, one with a row for
        each topic containing its exact/conceptual/total match numbers and
        percentages, and one with a bar chart with the numbers from each row.

    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/).
    
      

Get topic-document correlation histograms

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

    Optional parameter:
      bins (integer, default 10)

    Result:
      an object mapping topic IDs to pairs of the form
        [<array of bin sizes>, <array of bin borders>]

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

Get topic-topic correlations

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

    Optional parameters:
      format (string, default "csv" if deprecated use_json is not specified)
          one of "csv", "json", or "xlsx"; specifies the format of the returned
          data
      [deprecated] use_json (boolean, default false)
          if true, return JSON; if false, return CSV
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE format PARAMETER.

    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 the first worksheet, the rows
        and columns are topics and the entries are correlation values between
        the topics; topic names are in bold, and values have a 3-color scale.
        The second worksheet has a series of bar charts based on each of the
        rows of the first sheet.  The third worksheet has the columns from the
        first worksheet, each of which is sorted in increasing order of
        correlation and formatted with a 3-color scale.

    Returns the correlations of each topic with each other topic.
    
      

Get topic-subset correlations

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

    Optional parameters:
      format (string, default "csv" if deprecated use_json is not specified)
          one of "csv", "json", or "xlsx"; specifies the format of the returned
          data
      [deprecated] use_json (boolean, default false)
          if true, return JSON; if false, return CSV
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE format PARAMETER.

    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:
        An 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, and
        values are formatted with a 3-color scale.

    Returns the correlations of each topic with each subset.
    
      

Get topic timeline correlations

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

    Optional parameters:
      subsets (JSON-encoded array of strings, defaults to all documents)
          which subsets to count documents in.  Cannot contain more than one
          subset unless format is specified as "xlsx".
      [deprecated] subset (string, defaults to all documents)
          subset to count documents in
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE subsets PARAMETER.
      interval (string, default "document")
          one of "year", "quarter", "month", "week", "day", "hour", or
          "document"
      format (string, default "csv" if deprecated use_json is not specified)
          one of "csv", "json", or "xlsx"; specifies the format of the returned
          data
      [deprecated] use_json (boolean, default false)
          if true, return JSON; if false, return CSV
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE format PARAMETER.

    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:
        An 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, and values are
        formatted with a 3-color scale.

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

Terms

List terms

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

    Optional parameters:
      limit (integer, default 10, max 50000)
          number of terms to return; applies only if terms are not specified
      subset (string, defaults to all documents)
          subset from which to get terms
      terms (JSON-encoded array of strings, max length 50000)
          which terms to get instead of top terms

    Result:
      an array of term objects:

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

    Gives an array of objects for the terms with highest relevance in the
    subset, or for the terms that you specify.
    
      

Ignore a term

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

    Required parameter:
      term (string)
          term to ignore

    Optional parameter:
      substring (boolean, default false)
          see below for more information

    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 /api/v4/projects/<account>/<project_id>/terms/ignorelist/

    Required parameter:
      term (string)
          term to unignore

    Optional parameter:
      substring (boolean, default false)
          if true, unignores an ignored substring; if false, unignores an
          ignored complete string

    Result:
      "OK" or "Not Found"

    Tells the relevance calculator to stop ignoring a particular term.
    
      

List ignored terms

GET /api/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 /api/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 /api/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 /api/v4/projects/<account>/<project_id>/terms/restem/

    Result:
      an object mapping "from_term"s to "to_term"s

    Shows all the restem information for the project.
    
      

Search terms

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

    Required parameter (specify at least one):
      text (string)
      topic (string)
      topics (JSON-encoded array of strings)
      terms (JSON-encoded array of strings)
      vector (string)
      vectors (JSON-encoded array of strings)
      negative (JSON-encoded object)
      zero (JSON-encoded object)

    Optional parameters:
      limit (integer, default 10)
          number of terms to return
      domain (boolean, default true)
          if false, results can include not just the terms that appear in the
          project, but also terms from the background space
      subset (string, defaults to all documents)
          subset from which to get terms (if domain is true)

    Result:
      {"search_vector": <pack64'd search vector>,
       "search_results": <array 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 an array of pairs for the terms most correlated
    with it.  The first item in each pair is the full term object, 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 /api/v4/projects/<account>/<project_id>/terms/doc_counts/

    Optional parameters:
      terms (JSON-encoded array of strings, defaults to the top terms)
          which terms to include
      limit (integer, default 100)
          number of terms to include
      subsets (JSON-encoded array of strings, defaults to all documents)
          which subsets to count documents in.  Cannot contain more than one
          subset unless format is specified as "xlsx".
      [deprecated] subset (string, defaults to all documents)
          subset to count documents in
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE subsets PARAMETER.
      format (string, default "csv" if deprecated use_json is not specified)
          one of "csv", "json", or "xlsx"; specifies the format of the returned
          data.
      [deprecated] use_json (boolean, default false)
          if true, return JSON; if false, return CSV
          ONLY CONSIDERED IF NO VALUE SUPPLIED FOR THE format PARAMETER.

    Result:
      JSON version:
        [{"text": <most common surface text>,
          "num_exact_matches": <# docs that matched exactly>,
          "num_related_matches": <# additional related docs>},
         ...]

      CSV version:
        A CSV file in which the rows are terms (labeled with most common
        surface text) and their exact/conceptual/total match numbers and
        percentages.

      XLSX version:
        An XLSX file with two sheets per subset requested, one with a row for
        each term (labeled with its most common surface text) and its
        exact/conceptual/total match numbers and percentages, and one with a
        bar chart with the numbers from each row.

    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 /api/v4/projects/<account>/<project_id>/prediction/train/

    Optional parameters:
      regressors (JSON-encoded array of strings)
          array of names of target variables that should use regressors instead
          of classifiers (see below for details)
      classifiers (JSON-encoded array of strings)
          array 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": 2} and {"rating": 3},
    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": "2"} and {"rating": "3"}, the predicted "rating" for a new
    document will always be either "2" or "3".  If the "rating" is a number
    on some documents and a string on others, then it will be treated as
    numbers (and use a regressor) if all the strings can be interpreted as
    numbers, otherwise it will 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://support.luminoso.com/customer/portal/articles/2218420 .
    
      

Predict

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

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

    Result:
      an array of objects, each mapping target variables to values

    Tabulation:
      increases "documents uploaded" and "text uploaded"

    Takes a JSON-encoded array of document objects and computes their
    predicted values using any predictors that have been built (see the
    POST /prediction/train/ endpoint).  The documents only need to have a
    "text" field, and other fields (like "vector") will be ignored.

    Returns an array of objects, one for each document in the same order as the
    documents.  Each object 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.
    
      

Drivers [BETA]

GET /api/v4/projects/<account>/<project_id>/prediction/drivers/

    PLEASE NOTE: This endpoint is still in beta testing.  As such, its
    interface and output may change without warning.

    Optional parameters:
      nterms (integer, default 1000)
          number of top terms from the project to evaluate as drivers
      n_cluster_terms (integer, default 100)
          number of most influential terms to cluster into drivers.  Note that
          this is applied to both the positive and negative drivers, so there
          will be n_cluster_terms in positive clusters and n_cluster_terms in
          negative clusters.
      threshold (float, default 0.375)
          correlation over which two terms are determined to be in the same
          cluster

    Result:
      an object with a key for each trained regressor variable, with the value
      for each key being:

        {"coefficient_vector":
             vector of coefficients,
         "positive":
             array of driver objects with positive impact on the variable and
             high pertinence, in descending order of impact from the most
             positive driver,
         "negative":
             array of driver objects with negative impact on the variable and
             high pertinence, in descending order of impact from the most
             negative driver,
         "minor_positive":
             array of driver objects with positive impact and low pertinence,
             in descending order of impact from the most positive driver,
         "minor_negative":
             array of driver objects with negative impact and low pertinence,
             in descending order of impact from the most negative driver}

      Note that the minor_positive and minor_negative fields may be empty.

      Each of the driver objects has the form:

        {"term":
             stemmed form which defines the driver,
         "text":
             most common surface text of term,
         "vector":
             pack64'd vector for the term,
         "regressor_dot":
             a measure of the "impact" that the term has; can be interpreted as
             the number of points the predictor variable will increase (or
             decrease) by if this term is present,
         "driver_score":
             a similar measure of the term's "impact" that also depends on how
             related the term is to the documents in general,
         "similar_terms":
             an array of terms that are substantially similar (> threshold
             correlation) to the main driver term}

    Using any regressors that have been built (see the POST /prediction/train/
    endpoint), compute the terms most associated with the coefficient vector
    for that regressor.  Any classifiers are ignored.  These terms are then
    further scored by how much they influence the predictor. 
    
      

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/

    Optional parameter:
      accounts_only (boolean, default false)
          If true, then only accounts are returned as part of a user's
          permissions.  If false, then permissions on sharing groups are listed
          as well.

    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.
    
      

Reset password

POST /api/v4/user/password/

    Required parameters:
      data (object)
          the data from the URL sent by email
      signature (string)
          the signature from the URL sent by email
      password (string)
          the new password (for password requirements, see
          http://support.luminoso.com/customer/portal/articles/1934871 )

    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 /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.
    
      

Accept invitation

POST /api/v4/user/accept_invitation/

    Required parameters:
      data (object)
          the data from the URL sent by email
      signature (string)
          the signature from the URL sent by email
      create (boolean)
          true to create a new user, false for existing users

    Additional required parameters if "create" is true:
      full_name (string)
      password (string) (for password requirements, see
        http://support.luminoso.com/customer/portal/articles/1934871 )

    Result:
      "Joined account."

    If "create" is true, creates a new user and adds the user to the account
    given in the data.  If "create" is false, joins the user to the account,
    giving the account's admins the ability to modify the user's permissions
    on the account.

    "data" and "signature" will only be valid if they were generated by an
    invitation from an account admin.
    
      

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 earliest to latest).

    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)
          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/

    Optional parameter:
      accounts_only (boolean, default false)
          if true, then only accounts are returned as part of a user's
          permissions; if false, then permissions on sharing groups are listed
          as well.

    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.
    
      

Other

Ping

GET/PUT/POST/DELETE /api/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.
    
      

List supported languages

GET /api/v4/supported_languages/

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

Get version identifier

GET /api/v4/version/

    Result:
      version identifier (as a string)