{"host":"4cat.oilab.nl","info":{"contact":{"email":"noreply@4cat.oilab.nl"},"description":"This API allows interfacing with the 4CAT Capture and AnalysisToolkit, offering endpoints through which one may query our corpora via keyword-based search, and run further analysis on the results.","title":"4CAT: Capture and Analysis Toolkit RESTful API","version":"1.0.0"},"paths":{"/api/check-processors/":{"get":{"description":"Check processor status","operationId":"check_processor-get","parameters":[{"description":"A JSON-encoded list of dataset keys to get the status of","in":"query","name":"subqueries","required":true,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A list of dataset data, with each dataset an item with a `key`, whether it had `finished`, a `html` snippet containing details, and a `url` at which the result may be downloaded when finished.","schema":{"items":{"properties":{"finished":{"type":"boolean"},"html":{"type":"string"},"key":{"type":"string"},"url":{"type":"string"}},"type":"object"},"type":"array"}},"406":{"description":"If the list of subqueries could not be parsed."},"429":{"description":"If your request has been rate-limited."}},"summary":""}},"/api/check-query/":{"get":{"description":"Check dataset status","operationId":"check_dataset-get","parameters":[{"description":"ID of the dataset for which to return the status","in":"query","name":"key","required":true,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"Dataset status, containing the `status`, `query`, number of `rows`, the dataset `key`, whether the dataset is `done`, the `path` of the result file and whether the dataset is `empty`.","schema":{"properties":{"done":{"type":"boolean"},"empty":{"type":"boolean"},"is_favourite":{"type":"boolean"},"key":{"type":"string"},"path":{"type":"string"},"query":{"type":"string"},"rows":{"type":"integer"},"status":{"type":"string"}},"type":"object"}},"404":{"description":"If the dataset does not exist."},"429":{"description":"If your request has been rate-limited."}},"summary":"Requires authentication by logging in or providing a valid access token."}},"/api/check-search-queue/":{"get":{"description":"Get the amount of search query datasets yet to finish processing.","operationId":"check_search_queue-get","parameters":[],"produces":["application/json"],"responses":{"200":{"description":"An JSON array with search jobtypes and their counts.","schema":{"items":{"type":"string"},"properties":{"count":{"type":"integer"},"jobtype":{"type":"string"}},"type":"array"}},"429":{"description":"If your request has been rate-limited."}},"summary":""}},"/api/datasource-call/{datasource}/{action}/":{"get":{"description":"Call datasource function","operationId":"datasource_call-get","parameters":[{"description":"datasource","in":"path","name":"datasource","required":true,"type":"string"},{"description":"Action to call","in":"path","name":"action","required":true,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A JSON object"},"429":{"description":"If your request has been rate-limited."}},"summary":"Datasources may define custom API calls as functions in a file 'webtool/views.py'. These are then available as 'actions' with this API endpoint. Any GET parameters are passed as keyword arguments to the function."},"post":{"description":"Call datasource function","operationId":"datasource_call-post","parameters":[{"description":"datasource","in":"path","name":"datasource","required":true,"type":"string"},{"description":"Action to call","in":"path","name":"action","required":true,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A JSON object"},"429":{"description":"If your request has been rate-limited."}},"summary":"Datasources may define custom API calls as functions in a file 'webtool/views.py'. These are then available as 'actions' with this API endpoint. Any GET parameters are passed as keyword arguments to the function."}},"/api/delete-query/":{"delete":{"description":"Delete a dataset","operationId":"delete_dataset-delete","parameters":[{"description":"ID of the dataset to delete","in":"query","name":"key","required":true,"type":"string"},{"description":"Access token; only required if not logged in currently.","in":"query","name":"access_token","required":false,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A dictionary with a successful `status`.","schema":{"properties":{"status":{"type":"string"}},"type":"object"}},"404":{"description":"If the dataset does not exist."},"429":{"description":"If your request has been rate-limited."}},"summary":"Only available to administrators and dataset owners. Deletes a dataset, as well as any children linked to it, from 4CAT. Also tells the backend to stop any jobs dealing with the dataset."},"post":{"description":"Delete a dataset","operationId":"delete_dataset-post","parameters":[{"description":"ID of the dataset to delete","in":"query","name":"key","required":true,"type":"string"},{"description":"Access token; only required if not logged in currently.","in":"query","name":"access_token","required":false,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A dictionary with a successful `status`.","schema":{"properties":{"status":{"type":"string"}},"type":"object"}},"404":{"description":"If the dataset does not exist."},"429":{"description":"If your request has been rate-limited."}},"summary":"Only available to administrators and dataset owners. Deletes a dataset, as well as any children linked to it, from 4CAT. Also tells the backend to stop any jobs dealing with the dataset."}},"/api/get-available-processors/":{"get":{"description":"Get processors available for a dataset","operationId":"available_processors-get","parameters":[{"description":"Dataset key to get processors for","in":"query","name":"key","required":true,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"An object containing the `error` if the request failed, or a list of processors, each with a `name`, a `type` ID, a `description` of what it does, the `extension` of the file it produces, a `category` name, what types of datasets it `accepts`, and a list of `options`, if applicable.","schema":{"items":{"properties":{"accepts":{"items":{"type":"string"},"type":"array"},"category":{"type":"string"},"description":{"type":"string"},"extension":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":"array"}},"404":{"description":"If the dataset does not exist."},"429":{"description":"If your request has been rate-limited."}},"summary":""}},"/api/queue-processor/":{"post":{"description":"Queue a new processor","operationId":"queue_processor-post","parameters":[{"description":"Key of dataset to queue processor for","in":"query","name":"key","required":true,"type":"string"},{"description":"ID of processor to queue","in":"query","name":"processor","required":true,"type":"string"},{"description":"Access token; only required if not logged in currently.","in":"query","name":"access_token","required":false,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A list of dataset properties, with each dataset an item with a `key`, whether it had `finished`, a `html` snippet containing details, a `url` at which the result may be downloaded when finished, and a list of `messages` describing any warnings generated while queuing.","schema":{"additionalProperties":{"properties":{"finished":{"type":"boolean"},"html":{"type":"string"},"key":{"type":"string"},"messages":{"items":{"type":"string"},"type":"array"},"url":{"type":"string"}},"type":"object"},"type":"object"}},"429":{"description":"If your request has been rate-limited."}},"summary":"Queues the processor for a given dataset; with the returned query key, the processor status can then be checked periodically to download the result when available. Note that apart from the required parameters, further parameters may be provided based on the configuration options available for the chosen processor. Available options may be found via the `/get-available-processors/` endpoint."}},"/api/queue-query/":{"post":{"description":"Queue a 4CAT search query for processing into a dataset","operationId":"queue_dataset-post","parameters":[{"description":"Board ID to query","in":"query","name":"board","required":true,"type":"string"},{"description":"Data source ID to query","in":"query","name":"datasource","required":true,"type":"string"},{"description":"String to match in the post body","in":"query","name":"body_match","required":true,"type":"string"},{"description":"String to match in the post subject","in":"query","name":"subject_match","required":true,"type":"string"},{"description":"Timestamp marking the beginning of the match period","in":"query","name":"min_date","required":true,"type":"integer"},{"description":"Timestamp marking the end of the match period","in":"query","name":"max_date","required":true,"type":"integer"},{"description":"Access token; only required if not logged in currently.","in":"query","name":"access_token","required":false,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"The dataset key, which may be used to later retrieve dataset status and results."},"404":{"description":"If the datasource does not exist."},"429":{"description":"If your request has been rate-limited."}},"summary":"Requires authentication by logging in or providing a valid access token. Request parameters vary by data source. The ones mandated constitute the minimum but more may be required."}},"/api/request-token/":{"get":{"description":"Request an access token","operationId":"request_token-get","parameters":[],"produces":["application/json"],"responses":{"200":{"description":"An object with one item `token`"},"403":{"description":"If the user is logged in with an anonymous account."},"429":{"description":"If your request has been rate-limited."}},"summary":"Requires that the user is currently logged in to 4CAT."}},"/api/toggle-dataset-favourite/{key}":{"get":{"description":"'Like' a dataset","operationId":"toggle_favourite-get","parameters":[{"description":"Key of the dataset to mark as favourite.","in":"path","name":"key","required":true,"type":"string"}],"produces":["application/json"],"responses":{"200":{"description":"A JSON object with the status of the request","schema":{"properties":{"favourite_status":{"type":"boolean"},"success":{"type":"boolean"}},"type":"object"}},"404":{"description":"If the dataset key was not found"},"429":{"description":"If your request has been rate-limited."}},"summary":"Marks the dataset as being liked by the currently active user, which can be used for organisation in the front-end."}}},"swagger":"2.0"}