This section contains information about deprecated endpoints and parameters.
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.
Deprecation date: 2022-11-05
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-11-05, the skip_rebuild parameter was deprecated,
and its default value changed to true. Copied projects no longer build
automatically without an additional call to "Build project", unless skip_rebuild is
explicitly 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 (i.e., calls which copy a subset of documents from the original project)
will require a separate call to "Build project" once all desired documents have been
copied or uploaded to the target project.
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/.
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.
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.
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.
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.
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.
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)
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 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.
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.
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"}
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).
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": {"skip_sentiment": <boolean>,
"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.
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.
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.
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 true)
If skip_rebuild is true (default), the user is responsible for
manually triggering the build process (See "Build project"). This
scenario allows multiple sets of documents to be copied or uploaded
into the target project before a build occurs. Otherwise, if
skip_rebuiild is false, and any of the "destination", "search", or
"filter" parameters are supplied, a build in the target project will
automatically trigger.
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.
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 /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 /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>}
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 parameters:
keyword_expansion (JSON-encoded search expansion object)
Whether to compute keyword expansions for selected documents. See
"Keyword expansion" for details.
skip_sentiment (boolean, defaults to false)
If true, the sentiment build will not be performed.
sentiment_only (boolean, defaults to false)
If true, only the sentiment build will be performed.
new_sentiment (boolean, defaults to false)
If true, use the new microservice-based sentiment pipeline.
Recommended for large projects (> ~1 million documents).
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.
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 /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.
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 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 /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.
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 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 /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 /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.
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.
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 /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 /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 /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 /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 /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 parameter:
match_type (string)
match_type(total or exact)
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 /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.
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.
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 /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/
Result:
a shared concept list object
Retrieves the requested 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.
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 /api/v5/projects/<project_id>/concept_lists/<concept_list_id>/
Deletes the specified shared concept list, if it exists.
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 /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.
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.
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.
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.
PUT /api/v5/profile/
Optional parameters:
full_name (string)
default_workspace (string)
Updates your user information.
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.
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.
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.
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 /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.
PUT /api/v5/organizations/<organization_id>/
Required parameter:
name (string)
Change info about an 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.
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)
POST /api/v5/workspaces/
Required parameters:
organization_id (string)
name (string)
Result:
a workspace record
Create a workspace.
GET /api/v5/workspaces/<workspace_id>/
Result:
a workspace record
Get info about the workspace.
DELETE /api/v5/workspaces/<workspace_id>/
Result:
the record of the deleted workspace
PUT /api/v5/workspaces/<workspace_id>/
Required parameter:
name (string)
Change info about 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.
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.
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.
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-2024 Luminoso Technologies. All rights reserved.
Luminoso API Documentation