Deprecations

This section contains information about deprecated endpoints and parameters.

Obsolete fields: project-wide sentiment share and sentiment counts

Sunset date: 2022-09-10

The "Get concept sentiment" endpoint provides a sentiment share (and the raw
counts) for each concept it returns, based on our calculation of sentiment at
the level of individual concepts.  It also returns the share and counts for the
project as a whole; this information is a remnant of our previous calculation
of sentiment on entire documents.  Though we moved from document-level to
concept-level sentiment with science version 2.2, "sentiment_share" and
"sentiment_counts" at the document level remained part of the return.

As we drop support for projects built with versions earlier than 2.2, we are
also removing this vestige of that older, less precise calculation.  The fields
"sentiment_share" and "sentiment_counts" will remain on the individual
concepts, but will disappear from the overall return after the sunset date.

Behavior change and deprecation: skip_rebuild on "Copy project"

Deprecation date: 2022-08-25
Removal date: 2023-04-25

The "skip_rebuild" parameter of the "Copy project" endpoint allows a user to
skip building the destination project until an explicit call to the
"Build project" endpoint is made for that project. (Note that this parameter is
only meaningful for calls to "Copy project" which either: supply an existing
project to copy into via the "destination" parameter; or, copy a subset of the
documents from the project using the "search" or "filter" parameters. If none
of these parameters are supplied, the source project will simply be copied 1:1
into the new project, and no build will occur.) The current default value of
"skip_rebuild" is false, meaning that the build happens automatically. However,
we encourage use of a workflow that copies projects with "skip_rebuild" set to
true. Doing so allows further calls to "Copy project" or "Add documents" on the
target project prior to kicking off a build, which saves time and resources by
only building the project once it is in its desired state.

On 2022-08-25, the skip_rebuild parameter will be deprecated, and its default value
changed to true; after this date, copied projects will no longer build
automatically without a call to "Build project", unless skip_rebuild is
specified as false.

On 2023-04-25, the skip_rebuild parameter will be removed. After this
date, all copied projects made using the "destination", "search", or "filter"
parameters will require a separate call to "Build project" once all desired
documents have been copied or uploaded to the target project.

Using the API

If you are interested in writing your own code to connect to this API, many of
the following sections will be helpful.  However, the easiest way to connect
is via our API client: https://pypi.org/project/luminoso-api/.

Logging in

While some endpoints can be used without authentication, most endpoints require
authentication with an API token.  You can acquire a long-lived API token by
logging into the UI, going to "Settings", and clicking on "Tokens".

Our Python API client (see "Using the API") can save the long-lived token after
you create it and automatically use it to handle authentication on subsequent
calls.  You can acquire a token through the UI as described above and tell the
client to save it; alternately, if you do not specify a token, you will be
prompted to log in with your username and password, and the client will acquire
and save one for you.

If you are using your own HTTP client, you'll need to acquire a token through
the UI and send it with each authenticated request.  To make an authenticated
request, include an "Authorization" HTTP header with the string "Token "
followed by your token.

Requests

Many endpoints accept resource IDs as part of the URL path.  This is indicated
by the use of <angle brackets> in the documented endpoint URL.

Endpoints also accept parameters in the query string or the request body.
Again, our Python API client will handle this for you.  If you are using your
own HTTP client, follow the following guidelines.

In query strings, boolean parameters should be passed as "true" or "false",
numeric and string parameters require no unusual encoding, and object or array
parameters should be encoded as JSON.  Of course, the query string must also be
urlencoded; your HTTP client almost certainly does this automatically.

In the request body, only JSON is accepted; it must consist of a single object
whose fields are the intended parameter values (without any further encoding),
and the content type must be set to "application/json".

Please note that, while many implementations of JSON allow "NaN" and "Infinity"
as numbers, our API will reject them as ill-formed either in a query string or
in a JSON body.

Typically the query string is used for GET and DELETE requests and the request
body for PUT and POST requests.  The Daylight API will accept parameters in
either form regardless of the request method, with the request body taking
precedence; however, following conventional practice will minimize your chance
of problems with HTTP client or proxy software.

Both the Daylight API and most HTTP clients limit the total length of a URL,
which restricts the size of query strings.  To work around this limitation, GET
endpoints in the API that may require large queries will generally also respond
to POST requests with identical results, as documented for each endpoint below.

Rate limits

By default, endpoints in this API may be called no more than ten times per
second.  If you make more than ten calls within a one-second timespan, the API
will return a 429 error (see "Responses").  If that happens, please pause a
moment before making further calls.  Any automated scripts that make rapid
calls to the API should take these limits into account, and should be prepared
to handle a 429 response.

Some endpoints may allow calls more frequently, or less frequently; those
differences are documented on a per-endpoint basis.
 

Responses

Successful requests return HTTP status code 200 and either null or a JSON
object (other than /api/v5/, which returns this documentation as HTML).  If the
endpoint has no useful data to return, the response will be null; otherwise,
the response will be a JSON object whose format is described in the endpoint's
documentation.

Example successful return from POST /api/v5/projects/ (see "Projects" for the
full return):

    {"project_id": "pr123456",
     "workspace_id": "a12b345c",
     "name": "Example Project",
     "description": "An example project",
     ...}

Unsuccessful requests return HTTP status codes of 400 and above.  The response
will be a JSON object having at minimum an "error" field containing a short
string code and a "message" field containing an English description of the
error.  Other fields may give additional details about the nature of the error.

Example unsuccessful return from POST /api/v5/projects/:

    {"error": "INVALID_PARAMS",
     "message": "The listed request parameter(s) must be supplied.",
     "parameters": ["language"]}

The possible error codes and their associated HTTP status codes are:

  400 - INVALID_PARAMS
    An error that indicates that one of several things has gone wrong with the
    parameters you supplied, e.g. one was unrecognized, or a required one was
    missing.  The message will provide more information.

  400 - PROJECT_LOCKED
    Normally this error indicates that while your project was being built you
    attempted to upload new documents or rebuild the project, neither of which
    is allowed.  If your project is not being built and you receive this error,
    the project may have a fault; contact Luminoso for assistance.

  400 - PROJECT_NOT_BUILT
  400 - SENTIMENT_NOT_BUILT
  400 - SENTIMENT_BUILD_FAILED
  400 - PROJECT_NEEDS_UPDATING
    Some project endpoints do not require you to have built the project yet:
    document uploading, of course, and things like changing the project's name
    or description.  Other endpoints rely on the science that results from the
    project being built, and some of those rely on the project's sentiment
    having also finished building.

    For endpoints that do require either the core build or the sentiment build
    to have finished, these errors indicate, respectively, that a project does
    not have a completed core build, or that it does not have a completed
    sentiment build (either because the system does not allow sentiment to be
    built or because a build is still running), or that a sentiment build has
    failed, or that the science in its build is no longer compatible with the
    API.

  400 - EMAIL_NOT_ENABLED
    This error indicates that the server was asked to send email but is not
    configured to do so.

  401 - AUTH_CREDS_INVALID
    This error indicates that a supplied password is incorrect.  It is only
    returned by endpoints (such as "Change password") that require "password"
    as a parameter.

  401 - NO_TOKEN
    This error indicates that you have not supplied an API token to an endpoint
    that requires authentication.  See "Logging in".

  401 - INVALID_TOKEN
    This error indicates that you are attempting to use an invalid or expired
    API token.  If you are using a short-lived token, it has most likely
    expired; log in again to get a new one.  If you are using a long-lived
    token, use the Daylight user interface to make sure it has not been
    deleted.

  403 - INADEQUATE_PERMISSION
    This error indicates that your request was properly authenticated, but that
    you do not have permission on the requested project, workspace, or other
    resource.  Note that for security reasons this is also the error returned
    if the requested resource does not exist, so you should check that you have
    specified the correct ID and that the resource has not been deleted.

  404 - NOT_FOUND
  405 - METHOD_NOT_ALLOWED
    These errors indicate that the endpoint you called does not exist or does
    not support the requested method.  Check that you have spelled the endpoint
    correctly and that the base portion of the URL is correct (e.g., includes
    "/api/v5/").

  429 - TOO_MANY_REQUESTS
    This error indicates that you have exceeded the number of requests per
    second for this endpoint (see "Rate limits" for more information).

The API may also return ERROR, usually with the status code 500, or EMAIL_ERROR
with the status code 503; these indicate an error on our end, and you should
contact Luminoso for assistance.

Filters

A filter is an array of objects, each giving a constraint on a metadata field.

For a metadata field of type "string" the object should have the form

    {"name": <field name>,
     "values": <array of values>}

expressing the constraint that a document must have any of the specified values
for the field.  (The array may be empty, but the filter will match no
documents.)

For a metadata field of type "number", "score", or "date", a filter can be
specified either as an array of values of the field's type (in the same manner
as for metadata fields of type "string"), or as a range. A range filter for a
metadata field of type "number" or "score" should have the form

    {"name": <field name>,
     "minimum": <number>,
     "maximum": <number>}

expressing the constraint that a document must have a value specified for the
field which falls within the specified range.  (One of "minimum" or "maximum"
may be omitted, but not both.)  Similarly for "date", the object should be

    {"name": <field name>,
     "minimum": <number or string>,
     "maximum": <number or string>}

where the number or string conforms to the general format restrictions on
dates (see "Dates").

Documents matched by the filter must match all of the given constraints; that
is, the filter matches the intersection of the selected subsets.  The filter
may be an empty array, in which case it will match all documents.

For instance, the filter

    [{"name": "State", "values": ["MA", "NH"]},
     {"name": "Rating", "maximum": 3}]

would return all documents whose "State" is either "MA" or "NH", and whose
"Rating" is less than or equal to 3.

Concept Selectors

Many endpoints operate on any one of a number of "concept selectors", which
allows the user to specify which concepts they want results for.  A concept
selector is an object with a "type" field that specifies which type of concept
to use, and that must be one of the following types, with additional fields as
follows:

    {"type": "top"} - uses the project's top concepts, by relevance
      - optional field "limit", an integer (default 10, max 50000)

    {"type": "concept_list"} - uses the concepts in a shared concept list
      - required field: exactly one of
        "concept_list_id", the ID of the shared concept list
        "name", the name of the shared concept list

    {"type": "specified"} - uses the specified concepts
      - required field "concepts", an array of concepts (see "Concepts")

    {"type": "related"} - uses concepts related to a specific search concept
      - required field "search_concept", a single concept on which to search
        (see "Concepts")
      - optional fields:
        "limit", an integer (default 10, max 50000)
        "min_doc_count", the minimum number of documents in the entire project 
            (not necessarily in the supplied filter) that the related concepts 
            must appear in to be returned (default 2)

    {"type": "suggested"} - uses our suggested clusters of concepts
      - optional fields:
        "limit", the number of top concepts to consider when creating clusters;
            an integer (default 500, max 5000)
        "num_clusters", an integer (default 7)
        "num_cluster_concepts", an integer (default 4)
        
    {"type": "sentiment_suggested"} - uses the most sentiment-bearing concepts in the project
      - optional field "limit", an integer (default 500, max 50000)

    {"type": "unique_to_filter"} - uses the top concepts, by relevance, that
      occur more often in a provided filter than outside it
      - optional field "limit", an integer (default 50, max 50000)

    {"type": "drivers_suggested"} - uses concepts that are drivers
      - required field "score_field", the field against which to evaluate
        concepts, as used in the "Get drivers" endpoint
      - optional field "limit", an integer (default 10, max 50000)

Sample concept selectors

Some sample concept selectors you might pass, and the result of passing them to
the "Get concepts" endpoint:

    {"type": "top", "limit": 20}
      - Returns the top 20 concepts in the project

    {"type": "concept_list", "concept_list_id": "18e4badb-d9ad-4b71-8efb-794b8be4bcf7"}
      - Returns the concepts from the list with ID "18e4badb-d9ad-4b71-8efb-794b8be4bcf7"

    {"type": "specified", "concepts": [{"texts": ["disappointed"]}]}
      - Returns one concept, based on the text "disappointed"

    {"type": "related", "search_concept": {"texts": ["disappointed"]}}
      - Returns the 10 concepts most related to the concept "disappointed"

    {"type": "suggested"}
      - Returns 28 concepts, categorized into 7 clusters of 4 concepts each

    {"type": "suggested", "num_clusters": 10, "num_cluster_concepts": 3}
      - Returns 30 concepts, categorized into 10 clusters of 3 concepts each

    {"type": "sentiment_suggested", "limit": 100}
      - Returns the 100 most sentiment-bearing concepts in the project

    {"type": "unique_to_filter", "limit": "10"}
      - Returns the ten top concepts that occur within a provided filter

    {"type": "drivers_suggested", "score_field": "Rating", "limit": 5}
      - Returns the five most important drivers for the "Rating" metadata field

Dates

Dates sent to the API, either as metadata on a document or a value in a filter,
must be in one of two formats.  The first is the subset of ISO 8601 time
formats recommended by RFC 3339, but only allowing the time zone Z: that is,
strings in the format

    <year>-<month>-<day>T<hours>:<minutes>:<seconds>Z or
    <year>-<month>-<day>T<hours>:<minutes>:<seconds>.<microseconds>Z

For example, August 4, 2017, 8:15 pm, would be written "2017-08-04T20:15:00Z".
(Note that, per RFC 3339, the T and Z may be lowercased; we will standardize
all strings to uppercase.)

The second format we accept is epoch time, i.e. the number of seconds since
midnight UTC on January 1, 1970.  In this format, the above time would be
expressed as 1501877700.

Dates returned by the API are in the string format given above.

Term management

A term management object is an object mapping term IDs to changes.  Term IDs
are the language-tagged forms found in the "term_id" field of the "terms" and
"fragments" arrays on documents, as described in "Documents".  "changes" is an
object which may include

  * "action": the name of an action that changes the way a term ID is treated
    when a project builds.  At the moment, the only valid action is:
    * "ignore": term IDs marked with this action will be entirely skipped over
      when the project builds, as if they were function words like "the" or
      "of".
    * "notice": term IDs marked with this action will stop being skipped over
      when the project builds.  This is intended to apply to function words
      that would normally be left out of the analysis, but which represent a
      genuine concept in this project, e.g. the number "529" in a project about
      financial services.
  * "new_term_id": a new term ID that will replace the term ID whenever it
    occurs.

If a term management object is sent in which a term ID's changes is an empty
object, the management information for that term ID will be removed.

An example of a term management object:

  {"enviornment|en": {"new_term_id": "environment|en"},
   "really|en": {"action": "ignore"}}

With this object stored in term management, a project subsequently built would
have "enviornment" and "environment" merged into the same concept, and would
have "really" entirely removed.

Field breakdowns

Some endpoints can break down their results across values of a metadata field,
as might be used to generate a histogram or bar chart.  These endpoints accept
objects specifying which fields should be broken down and how.

A breakdown object for a string field has the form

  {"name": <name of the metadata field>}

for a number or score field

  {"name": <name of the metadata field>, "interval": <positive number>}

and for a date field

  {"name": <name of the metadata field>,
   "interval": "year", "quarter", "month", "week", "day", or "hour"}

For example, to retrieve concept match counts for a project with birthday data
bucketed by year, supply the following:

  {"name": "birthday", "interval": "year"}

Keyword expansion

A project built with keyword-expansion parameters will compute semantically
related terms for each document selected and return them in a
"weighted_keyword_expansion" field on the document.

Note: Keyword expansion is part of Search Enhancement with Luminoso, a separate
application of Luminoso's science. If you would like to purchase access to this
functionality, contact support@luminoso.com.

To activate keyword expansion, pass a "keyword_expansion" object to the
"Build project" endpoint with two optional fields:
  
  "filter": a filter specification to restrict the documents for which related
  terms are computed (see "Filters"); defaults to all documents
  
  "limit": the maximum number of related terms to return per term in each
  document (default: 20)

Note that the higher the limit is set, the longer the build process will take;
we do not recommend setting a value higher than 20.

Some sample keyword expansion objects:

  {}
    - Calculates expanded keywords for all documents, based on the 20 most
      related concepts for each concept in each document

  {"filter": [{"name": "Rating", "maximum": 3}], "limit": 5}
    - Calculates expanded keywords only for documents with a "rating" field of
      up to 3, based on the 5 most related concepts for each concept

If a project has been built with keyword expansion, documents returned by the
API will include the key "weighted_keyword_expansion".  Its value is an
object mapping strings to numbers.  Each string is a concept related to the
document; the number reflects the strength of the concept's relation (on a
scale from 0 to 1, but nothing under .5 is included).

Projects

A project record has the form

    {"project_id": <string, an internal identifier>,
     "workspace_id": <string, the ID of the workspace that owns the project>,
     "name": <string, the project's name>,
     "description": <string, a description of the project>,
     "language": <string, a two-character language code>,
     "next_build_language": <string, a two-character language code representing
                             the language that will be used for the next build
                             of the project.>,
     "creator": <string, the username of the user that created the project>,
     "creation_date": <number, a timestamp>,
     "document_count": <integer, the total number of documents in the project>,
     "last_update": <number, a timestamp of when the project was last
                     modified>,
     "last_successful_build_time": <number, a timestamp of when the project's
                                    last successful build terminated, or null
                                    if project is unbuilt>,
     "last_build_info": <object, see below>,
     "permissions": <array, the permissions the user has on the project>}

A project record's "last_build_info" will always be an object.  If no build has
ever been started, the object will be empty.  Otherwise, the object will always
have at least the fields

    {"number": <integer, the number of the last build>,
     "science_version": <string, the version of the science used to build the
                         project>,
     "language": <string, the two-character code of the language used for
                  the build>
     "start_time": <number, a timestamp>,
     "stop_time": <either a timestamp (number) if the core build has finished,
                   or null if it is still running>,
     "sentiment": {"start_time": <number, a timestamp>,
                   "stop_time": <either a timestamp (number) if the sentiment
                                 build has finished, or null if it is still
                                 running>}}

To check whether a project's core build is still running, look at the
"stop_time" field on the record's "last_build_info".  To check whether a
project's sentiment build is still running, look at "stop_time" in
"last_build_info.sentiment".

If the sentiment build is still running, "last_build_info.sentiment" will also
contain "progress," a number between 0.0 and 1.0 representing what proportion
of the build has been completed.

If the core build is no longer running, the "last_build_info" will also contain
"success", a boolean.  If "success" is false, it will additionally contain
"reason", a string explaining briefly why the build failed.  If the sentiment 
build is no longer running, "last_build_info.sentiment" will also contain
"success", a boolean.

Create project

POST /api/v5/projects/

    Required parameters:
      name (string)
          readable name for the project
      language (string)
          the language for the project.  See "Get system status" for more
          information.

    Optional parameters:
      workspace_id (string, defaults to user's default workspace ID)
          ID of the workspace which should own the project
      description (string)
          description for the project

    Result:
      a project record

    Creates a project with a specified name in a specified language.  Project
    names and descriptions are changeable; the ID that comes back in the
    project record is an internal identifier and cannot be changed.

    A note about unique naming: you cannot create a project that has the same
    name as an existing project in your workspace.  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.
    

Add documents

POST /api/v5/projects/<project_id>/upload/

    Required parameter:
      docs (JSON-encoded array of document objects)

    Rate limit: this endpoint has no rate limit.

    Upload new documents to a project (see "Documents").  Note that documents
    do not become available until the project is built.
    

Copy project

POST /api/v5/projects/<project_id>/copy/

    Optional parameters (specify at most one):
      workspace_id (string, defaults to ID of the workspace that owns the original project)
          ID of the workspace that will own the new project
      destination (string, defaults to a new project)
          ID of an existing project into which to copy the documents

    Optional parameters:
      search (JSON-encoded concept object, defaults to no search)
          search used to limit documents
      filter (JSON-encoded filter, defaults to no filter)
          filter used to limit documents
      skip_rebuild (boolean, defaults to false)
          By default, a successful call to the /copy endpoint will
          automatically trigger a build in the target project (note that this
          is only the case if any of the "destination", "search", or "filter"
          parameters are supplied). If skip_rebuild is true, the user is
          responsible for manually triggering the build process. This scenario
          allows multiple sets of documents to be copied or uploaded into the
          target project before a build occurs; otherwise, the project might be
          built several times before it is in the desired final state, causing
          unecessary delays before a project can be used.

    Additional optional parameters (see below for defaults)
      name (string)
          readable name for the new project
      description (string)
          description for the new project

    Additional optional parameter (ignored if no search is specified)
      match_type (string, default "both")
          if "exact", returns only documents that contain exact matches for the
          texts in the search; if "conceptual", returns only documents
          containing conceptual matches and not containing exact matches; if
          "both", returns documents with either or both

    Additional optional parameter (ignored if not rebuilding)
      notify (boolean, defaults to false)
          if true, sends an email to the user who initiated the copy

    Result:
      a project record

    Copies some or all documents from the project with the given ID, either to
    a new project or to an existing project.  Returns the record of the target
    project.

    If "destination" is not given, and neither "search" nor "filter" is
    specified, the resulting new project will be an exact copy of the existing
    project, without rebuilding.  In this case, the "notify" parameter will be
    ignored.  Otherwise, the specified subset of documents will be added to a
    project, either new or existing, and the project will immediately be
    rebuilt.

    When copying into an existing project, "name" and "description" default to
    the target project's current name and description, but can be specified
    here to update the name and description.  When copying to a new project,
    the name defaults to "Copy of [source project name]" for full copies and
    "Partial copy of [source project name]" for partial copies; the description
    defaults to the source project's description.

    To avoid potential miscopying, copying a project will not work if it is
    currently building, nor if the destination is currently building.
    

List projects

GET /api/v5/projects/

    Optional parameters:
      fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include on each returned object; nonexistent fields
          are ignored
      workspace_id (string, defaults to all workspaces)
          which workspace to include projects from

    Result:
      an array of project records

    Returns the records for a user's available projects.  See "Projects" above
    for details about project records.
    

Get project info

GET /api/v5/projects/<project_id>/

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

    Result:
      the project record
    

Get project metadata

GET /api/v5/projects/<project_id>/metadata/

    Optional parameter:
      max_values (integer)
          the maximum number of values to send back for a string or number
          field.  If a field has more than this many values, it will be
          returned without "values".

    Result:
      {"result": <an array of objects describing the project's metadata fields,
                  sorted alphabetically by field name>}

    Metadata fields of type "string" are described by objects of the form

      {"name": <field name>,
       "type": "string",
       "values": [{"value": <field value>,
                   "count": <number of docs>},
                   ...]}

    Metadata fields of type "number" or "score" are described by objects of the
    form

      {"name": <field name>,
       "type": "<field type>",
       "minimum": <lowest value in the project>,
       "maximum": <highest value in the project>,
       "values": [{"value": <field value>,
                   "count": <number of docs>},
                  ...]}

    The "values" field for "number" metadata fields is not present if there
    are more than 100 different values in the project.

    Metadata fields of type "date" are described by objects of the form

      {"name": <field name>,
       "type": "date",
       "minimum": <earliest value in the project>,
       "maximum": <latest value in the project>}
    

Build project

POST /api/v5/projects/<project_id>/build/

    Optional parameter:
      notify (boolean, defaults to false)
          if true, sends an email to the user who started the job upon its
          completion

    Optional parameter:
      keyword_expansion (JSON-encoded search expansion object)
          Whether to compute keyword expansions for selected documents.  See
          "Keyword expansion" for details.
      Note: Keyword expansion is part of Search Enhancement with Luminoso, a
      separate application of Luminoso's science.  If you would like to
      purchase access to this functionality, contact support@luminoso.com.

    Initiates a build which processes uploaded documents and stores the
    results.

    This endpoint must be called after a project's documents are uploaded, and
    subsequently if new documents are added, the project's language is changed,
    or term management settings are changed.

    Only one build can run at a time on a given project; if another build is
    running on the specified project, this endpoint will return an error.
    

Edit project details

PUT /api/v5/projects/<project_id>/

    Required parameter (specify at least one):
      name (string)
          readable name for the project
      description (string)
          description for the project
      language (string)
          the language for the project. Updates the "next_build_language" field
          for the project, which will become its "language" when the project is
          next built. See "Get system status" for more information.

    Sets user-changeable information for the project; omitted fields are not
    changed.
    

Delete project

DELETE /api/v5/projects/<project_id>/

    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.
    

Vectorize text

POST /api/v5/projects/<project_id>/vectorize/

    Required parameter:
      texts (JSON-encoded array of strings)
          an array of texts to vectorize; each text must be less than 500,000
          characters

    Result:
      an array of objects, with each object containing the original text, a
      vector, terms, and fragments

    This does *not* save the texts, or add any of their information to
    the project!
    

Documents

Documents uploaded to a project are required to be of the form

    {"text": <string, required; maximum length 500,000 characters>,
     "title": <string, default "">
     "metadata": <array of metadata fields, default []>}

in which the text field is required, and the other fields are optional.  Any
extraneous fields are invalid and will result in an error upon upload.
Metadata fields on documents for upload must be of the form

    {"name": <field name>,
     "value": <field value>,
     "type": <metadata type: one of "string", "number", "date", "score">}

For instance:

    {"text": "Some text",
     "metadata": [{"name": "State", "value": "MA", "type": "string"},
                  {"name": "Rating", "value": 5, "type": "number"}]}

Documents requested from a built project have the form

    {"doc_id": <string>,
     "text": <string>,
     "title": <string>,
     "metadata": <array of metadata fields>,
     "terms": <array of term objects>,
     "fragments": <array of term objects>,
     "vector": <vector in pack64 format>,
     "match_score": <number measuring similarity to the search if one was
                     performed, else null>}

where a term object in a document's terms and fragments is an object with
the fields "term_id" (a string representation of the term) and "start" and
"end" (integer indexes into the document text).

Get documents

GET /api/v5/projects/<project_id>/docs/

    Optional parameters:
      filter (JSON-encoded filter, defaults to all documents)
          criteria for restricting which documents to match (see "Filters")
      search (JSON-encoded concept object, defaults to no search)
          concept to search for (see "Concepts"); restricts which documents to
          return and determines an ordering/ranking for the results
      limit (integer, default 100, max 25000)
          number of documents to return
      offset (integer, default 0)
          number of documents to skip before beginning
      fields (JSON-encoded array of strings, defaults to all fields)
          which fields to include in the returned documents (see "Documents"
          for a list of fields returned by default); nonexistent fields are
          ignored
      include_sentiment_on_concepts (boolean, default false)
          if true, the term and fragment objects on each document will include
          keys for "sentiment" (the string "positive", "negative", or
          "neutral") and "sentiment_confidence" (a number from 0 to 1
          representing confidence in the accuracy of the sentiment value)

    Additional optional parameter (ignored if no search is specified)
      match_type (string, default "both")
          if "exact", returns only documents that contain exact matches for the
          texts in the search; if "conceptual", returns only documents
          containing conceptual matches and not containing exact matches; if
          "both", returns documents with either or both

    Result:
      {"result": <array of document objects>,
       "total_count": <number of documents in the project>,
       "filter_count": <number of documents matching the filter>,
       "result_count": <number of documents matching the filter and search>,
       "search": <null if no search object is supplied, otherwise
                  {<concept object> with additional fields:
                   "match_count": <number of documents that matched any exact
                                   or related terms>,
                   "exact_match_count": <number of documents that matched any
                                         of the exact terms>}>}

    If a search is supplied, documents are returned ranked by "match_score",
    and only documents that contain an exact or conceptual match will be
    included.
    
    This endpoint also accepts POST requests to accommodate large queries.

Delete documents

POST /api/v5/projects/<project_id>/docs/delete/

    Required parameter:
      doc_ids (JSON-encoded array of strings)
          an array of document IDs to delete

    Rate limit: 1 per second

    Marks documents for removal from the project on the next rebuild.  Any
    strings in the "doc_ids" parameter that do not correspond to documents that
    exist in your project will be silently ignored.

    Note that this endpoint does not automatically trigger a rebuild, and the
    documents will remain in the project until you POST to /build/.
    

Terms

Terms represent the science underlying text, and thus in particular underlying
concepts, which are defined via texts.  Their IDs are the unified
representation of a particular concept, marked with a language tag for clarity.
For instance, the concept in an English project corresponding to the texts
"speak" and "speaks" and "speaking" and "spoke" will be "speak|en"; the concept
in a French project corresponding to "parlez" and "parlons" will be "parler|fr".

The primary use of terms in the API is term management; their IDs appear in a
list on concepts to allow management via term ID.

Get terms

GET /api/v5/projects/<project_id>/terms/

    Required parameter:
      term_ids (JSON-encoded array of strings, max length 50000)
          which terms to get statistics for

    Result:
      An array of term objects.  Each term object has the following form:

      {"term_id": <term with language tag>,
       "total_doc_count": <number of documents in the filter containing the
                           term, including fragments>,
       "distinct_doc_count": <number of documents in the filter containing the
                              term, not including fragments>,
       "relevance": <term's relevance within the filter>,
       "background_frequency": <number measuring the approximate frequency of
                                the term in the background corpus>,
       "display_text": <most common surface text for this term>,
       "all_texts": {<text>: <frequency> for all texts that correspond to the
                     term},
       "vector": <vector in pack64 format>}
    
    This endpoint also accepts POST requests to accommodate large queries.

Get term management information

GET /api/v5/projects/<project_id>/terms/manage/

    Result:
      an object mapping term IDs to "changes" objects

    Retrieves complete information about what term management has been added to
    this project.

    If you have added management information but not yet rebuilt your project,
    the changes described by the result will not yet have any effect.  The
    result returned by this endpoint will not tell you which changes have gone
    in since the last build.
    

Update term management information

PUT /api/v5/projects/<project_id>/terms/manage/

    Required parameter:
      term_management (JSON-encoded term management object)
          a term management object (see "Term management")

    Optional parameter:
      overwrite (boolean, default false)
          if true, overwrites all existing term management information with the
          term management object being sent; if false, overwrites information
          for term IDs that are included, but preserves any other existing term
          ID information

    Alters the project's term management information.  (Note that changes will
    not take effect until the project is rebuilt.)

    As an example of the "overwrite" parameter: suppose your existing term
    management information is

      {"enviornment|en": {"action": "ignore"},
       "really|en": {"action": "ignore"}}

    and you call this endpoint with the term management object

      {"enviornment|en": {"new_term_id": "environment|en"},
       "enviornmental|en": {"new_term_id": "environmental|en"}}

    If you set overwrite to true, this object will now become the entirety of
    the project's term management, and the word "really" will go back to not
    being ignored.  If you set overwrite to false, ignoring "really" will be
    kept, but the previous act of ignoring "enviornment" will be overwritten,
    and your new term management will be

      {"enviornment|en": {"new_term_id": "environment|en"},
       "enviornmental|en": {"new_term_id": "environmental|en"},
       "really|en": {"action": "ignore"}}

    To remove term management for a particular term_id, set its changes to an
    empty object.  To remove all term management information from a project,
    use an empty object for the term_management parameter and set "overwrite"
    to true.
    

Concepts

A concept is an object with keys that vary, both when sent to the API as a
parameter and when retrieved from the API as part of a result.  Individual
endpoints will provide more guidance; this section offers a general overview.

Concepts are fundamentally an array of one or more texts, and therefore all
concepts retrieved through the API will include a "texts" key whose value is an
array.  Concepts sent to the API must be objects containing the single field
"texts", an array of texts, e.g.

    {"texts": ["kermit", "miss piggy", "gonzo"]}
    {"texts": ["rainbow connection"]}

This kind of concept can be used as a search, or as part of an array of
specified concepts (see "Concept Selectors").

Terms in the "texts" array which start with a minus ("-") will be interpreted
as NOT terms and will be excluded from any results.  All other terms will be
interpreted as ORs.  For example, the following concept will match any
documents which are related to "kermit" or "miss piggy" unless those documents
exactly match "gonzo".

    {"texts": ["kermit", "miss piggy", "-gonzo"]}

See the documentation on Advanced Concept Search for more details:
https://www.luminoso.com/getting-started-with-daylight/advanced-concept-search

Concept objects returned by the API will always have the following keys:

  * "texts": an array of texts.  For top concepts, this will be an array with
    one element, which is the display form of the concept.  For other
    concepts, this will be an array of texts that define the concept.
  * "name": the name of the concept.  For shared concepts, this is the name
    that was given to the concept, for other concepts, it is the
    comma-separated list of texts in "texts".
  * "exact_term_ids": the term IDs of terms that match the text exactly.
  * "excluded_term_ids": the term IDs of any terms that were excluded from the
    concept, if Advanced Concept Search is enabled.
  * "vectors": an array of the concepts vectors in pack64 format.  If Advanced
    Concept Search is enabled, this will include a vector for each term in
    exact_term_ids.  Otherwise, it will be a single vector for the concept as
    a whole. 
  * "relevance": a number score for ranking concepts, based on their frequency
    in a project and their background frequency.  Shared concepts, specified
    concepts, or searches defined with multiple texts have a relevance of 0.

Driver concepts (those returned by the "Get drivers" endpoint or via the
drivers_suggested concept selector) will also have:

  * "average_score": the average score of documents that match this
    concept.
  * "impact": a value conveying how much higher or lower in score are
    documents that match this concept, compared to the overall average.
  * "baseline": the average score of all documents matching this filter,
    which doesn't depend on the term, so it's the same for all rows.
  * "confidence": a measure of our confidence in this concept's impact as
    a driver.

Other keys that may appear on concepts under given circumstances:

  * "color" and "shared_concept_id": for shared concepts only.
  * "match_score": for searches only.  A score for ranking concepts, based on
    how well they match a given search.
  * "match_count", "exact_match_count": for match count endpoints only.
  * "related_term_ids": an array of related terms, returned on the search
    concept in the "Get documents" endpoint only.
  * "importance": a combination of impact, confidence, and other factors
    used for ranking the results, for either concepts returned from a
    drivers_suggested concept selector, or from the "Get drivers" endpoint
    when called without a concept selector.

A note about ordering: different concept selectors will order their results in
different ways.  Specified concepts are returned in the order provided;
concepts in shared concept lists are returned in their stored order.  Top
concepts are returned in order based on relevance score, most relevant first.
Suggested drivers are returned in order based on their "importance" score,
again with the highest scores first.

Get concepts

GET /api/v5/projects/<project_id>/concepts/

    Optional parameters:
      concept_selector (concept selector object, defaults to top concepts)
          which concepts to get (see "Concept Selectors")
      filter (JSON-encoded filter, defaults to all documents)
          criteria for restricting which documents must contain the concepts
          (see "Filters")

    Result:
      {"result": <an array of concepts>,
       "filter_count": <number of documents matching the filter>,
       "total_count": <number of documents in the project>,
       "search": <null if no search object is supplied, otherwise a concept
                 object>}

    Gives an array of concept objects, restricted to concepts that appear in
    documents that match the supplied filter.

    The returned concept objects will contain fields as described above,
    depending on the concept selector passed.
    
    This endpoint also accepts POST requests to accommodate large queries.

Get concept match counts

GET /api/v5/projects/<project_id>/concepts/match_counts/

    Optional parameters:
      concept_selector (concept selector object, defaults to top concepts)
          which concepts to use (see "Concept Selectors")
      filter (JSON-encoded filter, defaults to all documents)
          criteria for restricting which documents to count (see "Filters")
      breakdowns (JSON-encoded array of field breakdown specifications)
          specifies that the match counts should additionally be broken down
          against the provided metadata fields (see "Field breakdowns")

    Result:
      {"total_count": <number of documents in the project>,
       "filter_count": <number of documents matching the filter>,
       "match_counts": [{<concept object> with additional fields:
                         "match_count": <number of documents with an exact or
                                         related match to the concept within
                                         the filter>,
                         "exact_match_count": <number of documents with an
                                               exact match to the concept
                                               within the filter>},
                        ...],
       "breakdowns": [{"breakdown": <the provided specification>,
                       "buckets": [{"label": <bucket label>,
                                    "total_count": <total number of documents
                                                    in the bucket>,
                                    "filter_count": <number of documents in
                                                     the bucket matching the
                                                     filter>,
                                    "match_counts": <array similar to above>},
                                   ...]},
                      ...]
      }

    Counts the documents matching concepts in the project.  Always provides
    the total count of matching documents for each concept (in the provided
    filter, if present).

    Optionally request that the matches also be broken down against specified
    metadata fields.
    
    This endpoint also accepts POST requests to accommodate large queries.

Get concept-concept associations

GET /api/v5/projects/<project_id>/concepts/concept_associations/

    Optional parameter:
      concept_selector (concept selector object, defaults to top concepts)
          which concepts to use (see "Concept Selectors")

    Result:
      [{<concept object> with additional field:
        'associations': [
            {<concept object> with additional field:
             'association_score': <association score>
            },
            ...]
        },
       ...]

    Returns an array of concepts, each one with an "associations" field that
    lists all of the concepts with an additional association field.  For
    example, if you specify in the concept selector that you want the thirty
    concepts most related to "purchase", the endpoint will return thirty
    concepts, each one having those thirty concepts in its "associations"
    field, with an "association_score" on each.
    
    This endpoint also accepts POST requests to accommodate large queries.

Get concept-filter associations

GET /api/v5/projects/<project_id>/concepts/filter_associations/

    Optional parameters:
      concept_selector (concept selector object, defaults to top concepts)
          which concepts to use (see "Concept Selectors")
      filters (JSON-encoded array of filters, defaults to all documents)
          an array of filter objects with which to get concept associations.

    Result:
      An array of result objects, one for each filter provided.  Each result
      object has the form:

      {"filter": <filter object>,
       "filter_count": <number of documents in the project matching the
                        filter>,
       "concepts": [{<concept object> with additional field:
                     "association score": <score>},
                    ...]
      }

    Any filter objects that matched no documents will contain null association
    values.
    
    This endpoint also accepts POST requests to accommodate large queries.

Get drivers

GET /api/v5/projects/<project_id>/concepts/score_drivers/

    Required parameter:
      score_field (string)
          the name of the score field against which to evaluate concepts

    Optional parameter:
      filter (JSON-encoded filter, defaults to all documents)
          an array of filter objects to restrict documents

    Optional parameters (specify at most one):
      limit (integer, max 2000)
          how many of the most important drivers in the project to return
      concept_selector (concept selector object)
          which concepts to get (see "Concept Selectors")
      If neither parameter is specified, defaults to the 10 most important
      drivers in the project.

    Result:
      An array of concept objects.

      Suggested drivers are returned in order based on their importance
      ranking (with the highest scores first).  Results for other concept
      selectors are ordered as described in the "Concept Selectors" section.
    
    This endpoint also accepts POST requests to accommodate large queries.

Get concept sentiment

GET /api/v5/projects/<project_id>/concepts/sentiment/

    Optional parameters:
      concept_selector (concept selector object, defaults to sentiment suggestions)
          which concepts to get (see "Concept Selectors")
      filter (JSON-encoded filter, defaults to all documents)
          criteria for restricting which documents to count (see "Filters")
      include_examples (boolean, default false)
          if true, for each concept include example documents illustrating the
          different kinds of sentiment the concept can carry.

    Result:
      {"total_count": <number of documents in the project>,
       "filter_count": <number of documents matching the filter>,
       "sentiment_share": a <sentiment share object (see below)> for the
                          whole project, as filtered [DEPRECATED]
       "sentiment_counts": a <sentiment counts object (see below)> for the
                           whole project, as filtered [DEPRECATED]
       "match_counts": [{<concept object> with additional fields:
                         "match_count": <number of documents with an exact or
                                         related match to the concept within
                                         the filter>,
                         "exact_match_count": <number of documents with an
                                               exact match to the concept
                                               within the filter>},
                         "sentiment_share": a <sentiment share object, see
                                            below> for the concept,
                         "sentiment_counts": a <sentiment counts object, see
                                             below> for the concept
                        },
                        ...],
      }

    Returns match counts with additional information on sentiment.

    The sentiment share object is an object with the distribution of sentiment
    types (positive, neutral, negative) across documents that match a given
    concept, as follows:

        {
            "negative": <percentage of negative documents>,
            "neutral": <percentage of neutral documents>,
            "positive":  <percentage of positive documents>
        }

    The sentiment counts object is an object with the counts used to calculate
    the sentiment shares, as follows:

        {
            "negative": <count of negative documents>,
            "neutral": <count of neutral documents>,
            "positive": <count of positive documents>,
            "total": <total count of documents>
        }

    If include_examples is true, each concept will have an additional
    "example_documents" field mapping to an array of document objects
    illustrating each type of sentiment that the concept carries (i.e. for each
    term comprising the concept, a document in which the term is positive, a
    document for which the term is negative, and a document for which the term
    is neutral, if such a document exists).  Each document object will contain
    the additional field "example_details", which is an object of the form:

        {
            "term_ids": <array of term IDs being evaluated for sentiment in the
                         document>,
            "texts": <array of corresponding surface forms for each term ID>,
            "sentiment": <sentiment value for the term IDs in the document,
                          one of "positive," "neutral," or "negative">
        }

    For example, if your concept_selector were

        {"type": "specified", "concepts": [{"texts": ["coffee", "decaf"]}]}

    then the value of the "example_documents" field would be something like

        [
            {"_id": "uuid-00000000000000000000000000000001",
             "text": "The coffee was excellent!",
             [...rest of document fields],
             "example_details": {"term_ids": ["coffee|en"],
                                 "texts": ["coffee"],
                                 "sentiment": "positive"}},
            {"_id": "uuid-00000000000000000000000000000002",
             "text": "The coffee was bad, especially the decaf.",
             [...rest of document fields],
             "example_details": {"term_ids": ["coffee|en", "decaf|en"],
                                 "texts": ["coffee", "decaf"],
                                 "sentiment": "negative"}},
            ...
        ]

    Suggested sentiment concepts are returned in order based on their
    importance ranking (with the highest values first).  Results for other
    concept selectors are ordered as described in the "Concept Selectors"
    section.
    
    This endpoint also accepts POST requests to accommodate large queries.

Shared concept lists

The endpoints in this section create, retrieve, update, and delete shared
concept lists.  A shared concept list is an object with the following fields:

    {"name": <string, the list's name>,
     "concept_list_id": <string, the list's ID>,
     "concepts": <array of shared concepts>}

These endpoints do not interact with the project's science.  The concepts in
their "concepts" arrays therefore have only the following fields:

      {"name": <shared concept name>,
       "shared_concept_id": <unique shared concept ID>,
       "color": <HTML hex color>,
       "texts": <array of strings that define the concept>}

Additionally, the endpoints in this section can be used with an unbuilt
project; you can work with your concept lists even before uploading data.  The
"Get concepts" endpoint, called with a concept selector with type "concept_list"
(see "Concept Selectors"), will retrieve concepts from a shared concept list
that include their science, i.e. the exact_term_ids and vector.

As noted above, the concepts in a shared concept list have unique IDs.  Those
IDs are assigned when the concepts are first added to the list (either on list
creation or when new concepts are added to an existing list) and do not change;
but if you delete a concept and re-add an identical concept, or if you use the
"Edit shared concept list details" endpoint to overwrite an array of concepts
with an identical array, the unique IDs will *not* be preserved.  The IDs are
also unique even across lists, so two otherwise identical concepts--with the
same name, texts, and color--will have different IDs, whether on the same list
or different lists, and modifying one will not affect the other.

List shared concept lists

GET /api/v5/projects/<project_id>/concept_lists/

    Optional parameter:
      include_concepts (boolean, default true)
          if false, the "concepts" array will be excluded from each list

    Result:
      an array of shared concept list objects

    Retrieves the shared concept lists for a project.
    

Get shared concept list details

GET /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/

    Result:
      a shared concept list object

    Retrieves the requested shared concept list.
    

Create shared concept list

POST /api/v5/projects/<project_id>/concept_lists/

    Required parameter:
      name (string, cannot be empty, ignores surrounding whitespace)
          name for the shared concept list

    Optional parameters:
      concepts (JSON-encoded array of shared concept objects, defaults to an empty array)
          array of shared concepts to store in the list; see below for more
          information on fields that these objects allow or require
      overwrite (boolean, default false)
          if true, overwrites any shared concept list that might have the same
          name

    Result:
      a shared concept list object

    Create a shared concept list with the given name and concepts.

    Objects in the "concepts" array must include "texts", an array of strings.
    They may optionally include "name" and "color"; if these are not included,
    this endpoint will set defaults (the comma-separated list of texts in
    "texts", for the name; #808080, for the color).  They cannot include
    "shared_concept_id", which is set internally.

    If there is already a concept list with the same name, and the "overwrite"
    parameter is true, the existing list will be deleted.  If the "overwrite"
    parameter is false, this endpoint will return an error.
    

Edit shared concept list details

PUT /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/

    Required parameter (specify at least one):
      name (string, cannot be empty, ignores surrounding whitespace)
          new name for the concept list
      concepts (JSON-encoded array of shared concept objects)
          new array of shared concepts to store in the list

    Makes changes to an existing shared concept list.  For details about the
    contents of the concepts array and what defaults are set, see the
    "Create shared concept list" endpoint above.

    Note that specifying "concepts" will overwrite the list's current array of
    concepts, and in doing so will assign a new "shared_concept_id" to each
    concept, even if an identical concept exists in the list being overwritten;
    to modify the array without overwriting, see "Add concepts to a list" and
    other endpoints below.
    

Delete shared concept list

DELETE /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/

    Deletes the specified shared concept list, if it exists.
    

Add concepts to a list

POST /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/concepts/

    Required parameter:
      concepts (JSON-encoded array of shared concept objects)
          See "Create shared concept list" for more information on fields that
          these objects allow or require

    Optional parameter:
      position (integer, default 0)
          position to insert the concepts into (0 = first)

    Result:
      an array of concept objects

    Creates new concepts in a shared concept list.  For details about the
    contents of the concepts array and what defaults are set, see the
    "Create shared concept list" endpoint above.

    The concepts in the returned array are only those that have been added
    (including their shared concept IDs), and not the full newly-updated array
    of concepts in the shared concept list.
    

Delete concepts from a list

DELETE /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/concepts/

    Required parameter:
      shared_concept_ids (JSON-encoded array of strings)
          an array of shared concept IDs to delete

    Deletes the specified concepts, if present, from a shared concept list.
    

Reorder concepts in a list

PUT /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/concepts/order/

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

    Sets the order of concepts in a shared concept list to the order given.
    Existing concepts not included will be reordered at the end; non-existent
    concepts specified in the order will be ignored.
    

Modify selected concepts within a list

PUT /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/concepts/

    Required parameter:
      concepts (JSON-encoded array of shared concept update objects)
          an array of shared concept update objects including at least a
          "shared_concept_id" and any of "texts", "name", or "color"

    Updates the concepts in a shared concept list, based on the provided update
    objects.  Matches the ID on each update object with a concept in the list
    (ignoring any update object with no corresponding concept), and updates the
    concept using the provided fields.
    

Profile

Get user profile

GET /api/v5/profile/

    Gets this user's profile.

    Result:
      {"username": <username>,
       "full_name": <full name>,
       "global_permissions": <array of permissions this user has globally>,
       "default_workspace": <ID of default workspace>,
       "workspaces": [{"workspace_id": <workspace ID>,
                       "name": <workspace name>,
                       "organization_id": <ID of the workspace's organization>,
                       "permissions": <array of permissions this user has on
                                       this workspace>},
                      ...],
       "organization_id": <ID of this user's organization>,
       "organizations": [{"organization_id": <organization ID>,
                          "name": <organization name>,
                          "permissions": <array of permissions this user has on
                                          this organization>},
                         ...]
      }

    "workspaces" will contain one object for each workspace you have any
    permissions on.  "organizations" will contain one object for each
    organization such that either you have permissions on it or you have
    permissions on one of its workspaces.
    

Modify user profile

PUT /api/v5/profile/

    Optional parameters:
      full_name (string)
      default_workspace (string)

    Updates your user information.
    

Change password

PUT /api/v5/profile/password/

    Required parameters:
      old_password (string)
      new_password (string)
          for password requirements, see
          https://www.luminoso.com/settings-guide/change-password

    Changes the password of the current user.

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

Recover password

POST /api/v5/profile/password/reset/

    Required parameter:
      email (string)
          the user's email address

    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.
    

Users

Delete users

POST /api/v5/users/delete/

    Required parameter:
      usernames (JSON-encoded array of strings)
          an array of usernames to delete

    Deletes the listed users from Daylight.

    You must have manage permissions on all of the users' owner workspaces, and
    the users must be in the system. If any permission is missing, or there are
    non-existent users, a 403 abort is thrown.
    

Organizations

Get organization info

GET /api/v5/organizations/<organization_id>/

    Result:
      an organization object:

        {"organization_id": <organization ID>,
         "name": <organization name>,
         "users": [{'username': <username of user in the organization>,
                    'full_name': <the user's full name>,
                    'role': <the user's role on the organization>}
                   ...]
        }

    Get info about the organization.
    

Get usage for an organization

GET /api/v5/organizations/<organization_id>/usage/

    Rate limit: 1 per second

    Result:
      {"months": [
        {"start": "YYYY-MM-DD",
         "docs_uploaded": <number>,
         "docs_refunded": <number>,
         "workspaces": [{"workspace_id": <workspace ID>,
                         "name": <workspace name>,
                         "docs_uploaded": <number>,
                         "docs_refunded": <number>},
                         ...]},
       ...],
       "billing_periods": [
         {"start": "YYYY-MM-DD",
          "end": "YYYY-MM-DD",
          "docs_uploaded": <number>,
          "docs_refunded": <number>,
          "document_limit": <number or null>},
        ...]
      }

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

    Each object in the "months" array has a date string indicating the start of
    the month (e.g. "2018-08-01" for August, 2018), the number of documents
    uploaded in that month, the number of documents refunded in that month, and
    an array breaking down usage by workspace.  The array includes one entry
    for each workspace on which you have permission to view usage data, plus
    one entry aggregating usage across all other workspaces.  It is sorted by
    workspace name, with the aggregated entry for all other workspaces at the
    end.

    On each object in the "billing_periods" array, "start" and "end" are date
    strings of the form "YYYY-MM-DD" that indicate the days on which the period
    starts and ends. Each billing period also contains values for the document
    limit (can be none), the number of documents uploaded, and the number of
    documents refunded in that period.
    

Update organization details

PUT /api/v5/organizations/<organization_id>/

    Required parameter:
      name (string)

    Change info about an organization.
    

Edit users' roles in organization

PUT /api/v5/organizations/<organization_id>/users/

    Required parameters:
      usernames (JSON-encoded array of strings)
          an array of usernames to edit
      role (string)
          the role to assign to the specified users

    Edit the roles of users in the organization.  Nonexistent users and users
    who are not members of the organization will be ignored.
    

Workspaces

A workspace record has the form

    {"workspace_id": <string, an internal identifier>,
     "name": <string, the workspace's name>,
     "organization_id": <string, the ID of the organization the workspace
                         belongs to>}

Additionally, if the workspace is in your organization or if you are an admin
on the workspace, the record will include the following fields:

  "projects", an array of objects with "project_id" and "name" fields, one for
              each project in the workspace
  "users", an array of objects with "username", "full_name", and "role", one
           for each user with an explicit role on the workspace (i.e., not
           users with a role on the workspace based on their role on the
           workspace's organization)

Create workspace

POST /api/v5/workspaces/

    Required parameters:
      organization_id (string)
      name (string)

    Result:
      a workspace record

    Create a workspace.
    

Get workspace info

GET /api/v5/workspaces/<workspace_id>/

    Result:
      a workspace record

    Get info about the workspace.
    

Delete workspace

DELETE /api/v5/workspaces/<workspace_id>/

    Result:
      the record of the deleted workspace
    

Update workspace details

PUT /api/v5/workspaces/<workspace_id>/

    Required parameter:
      name (string)

    Change info about a workspace.
    

Remove users from a workspace

POST /api/v5/workspaces/<workspace_id>/users/remove/

    Required parameter:
      usernames (JSON-encoded array of strings)
          an array of usernames to remove from the workspace

    Remove users from the workspace.  Nonexistent users will be ignored.
    

Edit users' roles in workspace

PUT /api/v5/workspaces/<workspace_id>/users/

    Required parameters:
      usernames (JSON-encoded array of strings)
          an array of usernames to edit
      role (string)
          the role to assign to the specified users

    Edit the roles of users in the workspace.  Nonexistent users will be
    ignored.
    

Invite user to workspace

POST /api/v5/workspaces/<workspace_id>/invite_user/

    Required parameters:
      email (string)
          email address of user to invite
      role (string)
          which role to give the user on the workspace

    Invites a user to join your workspace 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.
    

Other

Get system status

GET /api/v5/status/

    Result:
      {"languages": [{"code": <language code>, "name": <language name>}, ...],
       "version": <version identifier>,
       "science_version": <science version identifier>,
       "minimum_science_version": <science version identifier>,
       "support_email": <email for support>}

    This endpoint provides system-wide information about this instance of
    Daylight.

    The version identifier string uses the software build date, and thus will
    be consistent across deployments of the same code.

    The science version identifier string indicates the current version of the
    science being used to build projects (e.g., "2.0" or "2.0.1"); it can be
    compared against the version returned on project records (see "Projects")
    to determine whether a rebuild of the project is warranted.

    The minimum science version is the earliest science version that is still
    compatible with the API.  If a project's science version is lower than the
    minimum science version, attempting to use its science endpoints will
    yield a 400 response (see "Responses").

    Language codes are the two-letter ISO 639-1 codes that can be supplied as
    values to endpoints that take a "language" parameter.  For instance, one
    object in the "languages" array will be {"code": "en", "name": "English"}.

    "support_email" is support@luminoso.com for all of Luminoso's cloud
    installations; in an onsite installation, this will be the email set by
    the onsite administrator (or "", if email is not configured).
    

Luminoso Daylight®, powered by QuickLearn® | © 2019-2022 Luminoso Technologies. All rights reserved.