Please see the tabs below for the various API endpoints. See also the GitHub pages for the API/backend and client bindings for Python and R.
Note: To generate this documentation, run python -m amcat4 document
API Endpoints for querying
Construct an aggregate query. POST body should be a json dict with axes and/or aggregations keys,
and optional filters and queries keys:
:axes: list of dicts containing field and optional interval: [{'field': .., ['interval': ..]}, ...],
:aggregations: list of dicts containing field, function, and optional name: [{field, function, [name]}, ...]
:filters: see POST /query endpoint,
:queries: see POST /query endpoint,
}
For example, to get average views per week per publisher
{
'axes': [{'field': 'date', 'interval':'week'}, {'field': 'publisher'}],
'aggregations': [{'field': 'views', 'function': 'avg'}]
}
Returns a JSON object {data: [{axis1, ..., n, aggregate1, ...}, ...], meta: {axes: [...], aggregations: [...]}
List or query documents in this index. POST body should be a json dict structured as follows (all keys optional):
{
# Sorting
'sort': 'date' # sort by date
'sort': ['date', 'id'] # sort by date, then by id
'sort': [{'date': {'order':'desc'}}] # sort by date in descending order (see elastic docs below)
# Docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html
# Pagination
'sort':
'per_page': <number> # Number of documents per page
'page': <number> # Request a specific page
'scroll': <string> # Create a scroll request. Value should be e.g. 5m for 5 minutes
'scoll_id': <string> # Get the next page for the scroll request
# Control highlighting
'annotations': true # Return _annotations with query matches as annotations
'highlight': true # Highlight document. True highlights whole document
'highlight': {'number of fragments': 3} # Highlight up to 3 snippets per document (see elastic docs below)
# Docs: https://www.elastic.co/guide/en/elasticsearch/reference/7.17/highlighting.html
# select fields
'fields': field ## single field
'fields': [field1, field2] ## multiple fields
# elastic queries.
'queries': query, ## single query
'queries': [query1, query2], ## OR without labels
'queries': {label1: query1, label2: query2} ## OR with labels
# filters
'filters': {field: value}, ## exact value
{field: [value1, value2]}, ## OR
{field: {gt(e): value, lt(e): value} ## range or multiple
{field: {values: [v1,v2]} ## can also use values inside dict
}
}
Returns a JSON object {data: [...], meta: {total_count, per_page, page_count, page|scroll_id}}
}
API Endpoints for document and index management
List index from this server. Returns a list of dicts containing name, role, and guest attributes
Create a new index, setting the current user to admin (owner).
POST data should be json containing name and optional guest_role
Modify the index. Currently only supports modifying guest_role
POST data should be json containing the changed values (i.e. guest_role)
Modify the index. Currently only supports modifying guest_role
POST data should be json containing the changed values (i.e. guest_role)
Delete the index.
Upload documents to this server.
JSON payload should contain a `documents` key, and may contain a `columns` key:
{
"documents": [{"title": .., "date": .., "text": .., ...}, ...],
"columns": {<field>: <type>, ...}
}
Returns a list of ids for the uploaded documents
Get a single document by id
GET request parameters:
fields - Comma separated list of fields to return (default: all fields)
Update a document
PUT request body should be a json {field: value} mapping of fields to update
Get the fields (columns) used in this index
returns a json array of {name, type} objects
Set the field types used in this index
POST body should be a dict of {field: type}
Get the fields (columns) used in this index
AmCAT4 can use either Basic or Token-based authentication. A client can request a token with basic authentication and store that token for future requests.
Create a new token for the authenticated user
AmCAT4 can use either Basic or Token-based authentication. A client can request a token with basic authentication and store that token for future requests.
Create a new user. Request body should be a json with email, password, and optional (global) role
View the current user. Users can view themselves, writer can view others
Delete the given user. Users can delete themselves, admin can delete everyone, and writer can delete non-admin
Modify the given user.
Users can modify themselves (but not their role), admin can change everyone, and writer can change non-admin.
None