User guide
Academy
Code library
Widgets
APIs
Release notes
User guide
Academy
Code library
Widgets
APIs
Release notes
API docs by Redocly

Opendatasoft's Automation API Documentation (1.0)

Download OpenAPI specification:Download

E-mail: support@opendatasoft.com License: Copyright Opendatasoft

Opendatasoft REST API to manage your portal and its catalog

Datasets

Datasets are at the core of the platform. A dataset is composed of:

  • the actual data available on the portal (not available via the Automation API)
  • metadata like a title, a description and keywords describing the data, so users can discover it in the portal's catalog
  • configurations for processors, visualisation and security, which define the way data will be processed by the platform and made visible to users

Through the Automation API, it is possible to:

  • create datasets
  • attach resources to datasets
  • configure datasets processing pipeline, visualisations and security attributes
  • publish datasets

List datasets

List all the datasets that can be edited by this user.

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

dataset_id
string

Find a dataset from its dataset_id

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create dataset

Create a dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
dataset_id
string non-empty

Human-readable identifier of the dataset that can be modified when the dataset is not published

is_restricted
boolean

Defines if the dataset is visible for anonymous visitors.

  • If it is false, anyone having access to the domain will be able to see the dataset in the catalog. Users who have at least a ruleset declared for them (whether directly, through a group or both) will be able to see everything their rulesets grant access to. Users who do not have any ruleset declared for them (neither directly nor through a group) will be able to see what the default ruleset (default_security dataset property) grants access to.
  • If it is true, the dataset will only appear in the catalog for users who have a ruleset declared for them, either directly or through a group. Other users won't have any access to the dataset. The default_security ruleset has no effect for restricted datasets.
required
object (DatasetMetadata)

The data describing the dataset itself.

object (DatasetSecurity)

The dataset default security ruleset when the dataset is restricted. This ruleset applies to all users who do not have any ruleset declared for them

Responses

Request samples

Content type
application/json
{
  • "dataset_id": "counties-united-states-of-america",
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Response samples

Content type
application/json
{
  • "uid": "da_qf2hyt",
  • "dataset_id": "counties-united-states-of-america",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_published": false,
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Retrieve Dataset

Retrieve a dataset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "da_qf2hyt",
  • "dataset_id": "counties-united-states-of-america",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_published": false,
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Update Dataset

Update a dataset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
dataset_id
string non-empty

Human-readable identifier of the dataset that can be modified when the dataset is not published

is_restricted
boolean

Defines if the dataset is visible for anonymous visitors.

  • If it is false, anyone having access to the domain will be able to see the dataset in the catalog. Users who have at least a ruleset declared for them (whether directly, through a group or both) will be able to see everything their rulesets grant access to. Users who do not have any ruleset declared for them (neither directly nor through a group) will be able to see what the default ruleset (default_security dataset property) grants access to.
  • If it is true, the dataset will only appear in the catalog for users who have a ruleset declared for them, either directly or through a group. Other users won't have any access to the dataset. The default_security ruleset has no effect for restricted datasets.
required
object (DatasetMetadata)

The data describing the dataset itself.

object (DatasetSecurity)

The dataset default security ruleset when the dataset is restricted. This ruleset applies to all users who do not have any ruleset declared for them

Responses

Request samples

Content type
application/json
{
  • "dataset_id": "counties-united-states-of-america",
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Response samples

Content type
application/json
{
  • "uid": "da_qf2hyt",
  • "dataset_id": "counties-united-states-of-america",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_published": false,
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Delete Dataset

Delete the dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
""

Publish dataset

Make the dataset modifications available through the explore API. It may entail the processing of all the records.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Publish dataset metadata

Publish dataset metadata

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Abort dataset publishing

Stop the current processing job and keep the processed records available in the explore API.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Unpublish dataset

Remove the dataset from the explore API. Unpublishing a dataset does not delete the dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Copy dataset

Copy a dataset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "da_qf2hyt",
  • "dataset_id": "counties-united-states-of-america",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_published": false,
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Retrieve dataset status

Retrieves the current dataset status.

The dataset status describes the current state of a dataset, stating if it's published or not and the running operation. It is a finite state machine, with the following properties:

  • a single state at a time
  • the list of possible states, fully known
  • the list of all transitions, fully known, each with the actions and conditions that can trigger them
Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "status": "idle",
  • "previous": "processing",
  • "next": null,
  • "since": "2019-08-24T14:15:22Z",
  • "is_published": true,
  • "message": null,
  • "records_errors": [ ],
  • "params": { }
}

Dataset resources

Dataset resources

List extractors

List available extractors

Authorizations:
QueryAPIKeyHeaderAPIKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List dataset resources

List all resources that are linked to a dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

expand
string
Enum: "datasource.connection" "datasource.dataset"

The list of fields to expand.

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create dataset resource

Create a new resource for the dataset. For now the supported resources in the API are HTTP, (s)FTP, uploaded files, S3, Azure Blob Storage, dataset federation, Snowflake, JCDecaux, Sharepoint and Google Drive.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
type
required
string non-empty

extractor type that should handle this resource

title
required
string non-empty

friendly title

params
object

parameters passed to the extractor

required
object (Datasource)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    }
}

Response samples

Content type
application/json
Example
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Guess unsaved resource extractors

Guess the resource extractors

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
required
object (Datasource)

Responses

Request samples

Content type
application/json
{
  • "datasource": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Guess unsaved resource extractor parameters

Guess the extractor parameters

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
required
object (Datasource)
type
required
string

Responses

Request samples

Content type
application/json
{
  • "datasource": {
    },
  • "type": "csvfile"
}

Response samples

Content type
application/json
{
  • "extractor": "csvfile",
  • "params": {
    }
}

Preview unsaved resource records

In order to test a resource configuration, it can be useful to preview the data. This endpoint uses a resource configuration passed in the payload to generate a preview.

The preview is composed of the fields definitions and the content of the first records up to 20.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
required
object (Datasource)
type
required
string
object

Responses

Request samples

Content type
application/json
{
  • "datasource": {
    },
  • "type": "csvfile",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "records": [
    ]
}

Retrieve dataset resource

Retrieve one dataset resource specified by its uid.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt
query Parameters
expand
string
Enum: "datasource.connection" "datasource.dataset"

The list of fields to expand.

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Update dataset resource

Update one dataset resource specified by its uid.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt
Request Body schema: application/json
type
required
string non-empty

extractor type that should handle this resource

title
required
string non-empty

friendly title

params
object

parameters passed to the extractor

required
object (Datasource)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    }
}

Response samples

Content type
application/json
Example
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Delete dataset resource

Delete one dataset resource specified by its uid.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
""

Guess resource extractors

Guess the resource extractors

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clean cache of resource

Clean the cache of a given resource.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
""

Guess resource extractor parameters

Guess the resource extractor parameters

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "extractor": "csvfile",
  • "params": {
    }
}

Preview resource records

In order to test a resource configuration, it can be useful to preview the data. This endpoint uses the configuration of a resource specified by its uid to generate a preview.

The preview is composed of the fields definitions and the content of the first records up to 20.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "records": [
    ]
}

Recover realtime data

Recover the data of a realtime resource. The dataset must be published.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Delete realtime recovered data

Delete the recovered data of a realtime resource. The dataset must be published.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Enable realtime resource

Enable a realtime resource

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Disable realtime resource

Disable a realtime resource

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Renew realtime resource API key

Renew a realtime resource API key

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
resource_uid
required
string
Example: re_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "re_qf2hyt",
  • "type": "csvfile",
  • "title": "fromages.csv",
  • "params": {
    },
  • "datasource": {
    },
  • "updated_at": "2022-01-01T00:00:00Z"
}

Upload resource file

Upload a file to be used in a dataset resource. The HTTP request must be a multipart request with a file property.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "uid": "fromages.csv",
  • "filename": "fromages.csv",
  • "mimetype": "text/csv",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve dataset resource file

Retrieve a dataset resource uploaded file

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
file_uid
required
string
Example: fromages.csv

Responses

Response samples

Content type
application/json
{
  • "uid": "fromages.csv",
  • "filename": "fromages.csv",
  • "mimetype": "text/csv",
  • "created_at": "2019-08-24T14:15:22Z"
}

Download dataset resource file

Download a dataset resource file

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
file_uid
required
string
Example: fromages.csv

Responses

Response samples

Content type
application/json
{
  • "error_code": "not_found",
  • "message": "Not found."
}

Dataset metadata

Metadata is data describing the dataset itself. This is a set of fields describing the data, such as a title, a description, a list of keywords, a modification date, or whether the dataset is compliant to a specific geospatial norm. Adding metadata on a dataset is important to make sure it can be found, understood, and reused by users. In some cases, it can also be important for interoperability, to make sure other systems can understand the content of the dataset.

Dataset metadata are grouped within metadata templates that you can think of as namespaces. On top of the default metadata template, you may also find (depending on your domain's configuration) the Inspire, DCAT or CitadelJSON templates. Many other templates also exist and you can contact the support to define your own templates.

List all dataset metadata

Returns the set of metadata for the dataset with the given UID.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "default": {
    },
  • "visualization": { },
  • "internal": {
    },
  • "custom_template_name": {
    }
}

Update all dataset metadata

Update all dataset metadata at once. This operation replaces the dataset metadata with the given payload: if a metadata is omitted, it will be removed from the dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
required
object (DatasetMetadataDefault)

The standard set of metadata common to all Opendatasoft datasets.

object (DatasetMetadataVisualization)

This set of metadata is used to configure the dataset visualizations on your portal.

object (DatasetMetadataInternal)

This set of metadata is used for dataset configuration and won't appear on your portal.

object (DatasetMetadataCustom)

Additional values for custom metadata templates you have configured on your portal.

Responses

Request samples

Content type
application/json
{
  • "default": {
    },
  • "visualization": { },
  • "internal": {
    },
  • "custom_template_name": {
    }
}

Response samples

Content type
application/json
{
  • "default": {
    },
  • "visualization": { },
  • "internal": {
    },
  • "custom_template_name": {
    }
}

List a template's dataset metadata

Returns the set of metadata within the given template for the dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
template_name
required
string
Example: template_name

Metadata template name

Responses

Response samples

Content type
application/json
Example
{
  • "title": {
    },
  • "description": {
    },
  • "keyword": {
    },
  • "modified": {
    },
  • "modified_updates_on_metadata_change": {
    },
  • "modified_updates_on_data_change": {
    },
  • "geographic_reference": {
    },
  • "geographic_reference_auto": {
    },
  • "language": {
    },
  • "timezone": {
    },
  • "publisher": {
    },
  • "references": {},
  • "attributions": {
    }
}

Update a template's dataset metadata

Update dataset metadata within a given template. This operation replaces the dataset metadata with the given payload: if a metadata is omitted, it will be removed from the dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
template_name
required
string
Example: template_name

Metadata template name

Request Body schema: application/json
One of
required
object (DatasetMetadataValue)

Title of the dataset.

object (DatasetMetadataValue)

Description of the dataset.

object (DatasetMetadataValue)

Keywords to define the dataset and better find it through searches. Keywords are one of the catalog filters available in the front office of an Opendatasoft portal.

required
object (DatasetMetadataValue)

Date indicating when the dataset was last modified.

object (DatasetMetadataValue)

If the modified date should automatically be updated on metadata changes.

object (DatasetMetadataValue)

If the modified date should automatically be updated on data changes.

object (DatasetMetadataValue)

Geographic References.

object (DatasetMetadataValue)

Geographic References automatic computation.

required
object (DatasetMetadataValue)

Language of the data in the dataset.

object (DatasetMetadataValue)

Forces the dataset visualizations to use the defined timezone for the date and datetime fields. It avoids the dataset visualizations to depend on the timezone on which the user's computer is set.

object (DatasetMetadataValue)

Name of the person or organization who published the dataset.

object (DatasetMetadataValue)

Link to the source of the dataset.

object (DatasetMetadataValue)

Link to a source of the dataset that should be mentioned for legal reasons (e.g. if the license demands the mention of a specific source or organization).

Responses

Request samples

Content type
application/json
Example
{
  • "title": {
    },
  • "description": {
    },
  • "keyword": {
    },
  • "modified": {
    },
  • "modified_updates_on_metadata_change": {
    },
  • "modified_updates_on_data_change": {
    },
  • "geographic_reference": {
    },
  • "geographic_reference_auto": {
    },
  • "language": {
    },
  • "timezone": {
    },
  • "publisher": {
    },
  • "references": {},
  • "attributions": {
    }
}

Response samples

Content type
application/json
Example
{
  • "title": {
    },
  • "description": {
    },
  • "keyword": {
    },
  • "modified": {
    },
  • "modified_updates_on_metadata_change": {
    },
  • "modified_updates_on_data_change": {
    },
  • "geographic_reference": {
    },
  • "geographic_reference_auto": {
    },
  • "language": {
    },
  • "timezone": {
    },
  • "publisher": {
    },
  • "references": {},
  • "attributions": {
    }
}

Retrieve a metadata

Retrieve the metadata with the given name within the given template.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
template_name
required
string
Example: template_name

Metadata template name

template_field_name
required
string
Example: field_name

Metadata template field name

Responses

Response samples

Content type
application/json
{
  • "value": "Metadata value",
  • "remote_value": "Metadata value on the remote dataset, if there is one",
  • "override_remote_value": true
}

Update a metadata

Update the metadata with the given name within the given template.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
template_name
required
string
Example: template_name

Metadata template name

template_field_name
required
string
Example: field_name

Metadata template field name

Request Body schema: application/json
value
required
any

The effective metadata value. If the dataset is linked to a remote dataset and override_remote_value is false, this value will be the same as remote_value.

override_remote_value
boolean

Defines if the remote value is overridden (true), or if it is kept in sync with the value on the remote dataset. This property is present only if the dataset is linked to a remote dataset (a federated dataset for example).

Responses

Request samples

Content type
application/json
{
  • "value": "Metadata value",
  • "remote_value": "Metadata value on the remote dataset, if there is one",
  • "override_remote_value": true
}

Response samples

Content type
application/json
{
  • "value": "Metadata value",
  • "remote_value": "Metadata value on the remote dataset, if there is one",
  • "override_remote_value": true
}

Delete a metadata

Delete the metadata with the given name within the given template.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
template_name
required
string
Example: template_name

Metadata template name

template_field_name
required
string
Example: field_name

Metadata template field name

Responses

Response samples

Content type
application/json
""

Dataset security

The dataset security is the set of rules that defines who (which users / groups) can access what (which metadata / records / fields) at what frequency (API calls quota) for a given this dataset.

It is defined through 3 variables:

  • a general access policy that sets whether the dataset is accessible to anyone or just a few specific users. It is controlled through the is_restricted dataset property.
  • specific rulesets for users and groups. Those rulesets are managed using the dataset/{uid}/security/ API endpoints described in this section.
  • a default ruleset that applies to anybody else. It is controlled through the default_security dataset property.

List dataset user rulesets

List the dataset user-level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create dataset user ruleset

Create a dataset user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
object (DatasetSecurity)
permissions
Array of strings unique
Items Enum: "explore_restricted_dataset" "edit_dataset" "publish_dataset" "manage_dataset"

List of special permissions granted to the target.

required
object (RelatedUser)

The user targeted by this ruleset.

Responses

Request samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "user": {
    }
}

Retrieve dataset user ruleset

Retrieve a dataset user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
username
required
string
Example: louise.data
Request Body schema: application/json
object (DatasetSecurity)
permissions
Array of strings unique
Items Enum: "explore_restricted_dataset" "edit_dataset" "publish_dataset" "manage_dataset"

List of special permissions granted to the target.

required
object (RelatedUser)

The user targeted by this ruleset.

Responses

Request samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "user": {
    }
}

Update dataset user ruleset

Update a dataset user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
username
required
string
Example: louise.data
Request Body schema: application/json
object (DatasetSecurity)
permissions
Array of strings unique
Items Enum: "explore_restricted_dataset" "edit_dataset" "publish_dataset" "manage_dataset"

List of special permissions granted to the target.

required
object (RelatedUser)

The user targeted by this ruleset.

Responses

Request samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "user": {
    }
}

Delete dataset user ruleset

Delete a dataset user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
""

List dataset group rulesets

List the dataset group level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create dataset group ruleset

Create a dataset group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
object (DatasetSecurity)
permissions
Array of strings unique
Items Enum: "explore_restricted_dataset" "edit_dataset" "publish_dataset" "manage_dataset"

List of special permissions granted to the target.

required
object

The group targeted by this ruleset.

Responses

Request samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "group": {
    }
}

Retrieve dataset group ruleset

Retrieve a dataset group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
object (DatasetSecurity)
permissions
Array of strings unique
Items Enum: "explore_restricted_dataset" "edit_dataset" "publish_dataset" "manage_dataset"

List of special permissions granted to the target.

required
object

The group targeted by this ruleset.

Responses

Request samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "group": {
    }
}

Update dataset group ruleset

Update a dataset group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
object (DatasetSecurity)
permissions
Array of strings unique
Items Enum: "explore_restricted_dataset" "edit_dataset" "publish_dataset" "manage_dataset"

List of special permissions granted to the target.

required
object

The group targeted by this ruleset.

Responses

Request samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "security": {
    },
  • "permissions": [
    ],
  • "group": {
    }
}

Delete dataset group ruleset

Delete a dataset group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
""

Dataset processors

The Opendatasoft platform allows you to apply one or more processors to a dataset.

These processors are units of data transformation and other processing. Each processor represents a configurable operation that will be applied to all rows of a dataset.

Examples of what you can do with a processor include replacing text with a regex, geocoding an address into geographical coordinates, creating a new column that contains the result of a substraction between two existing columns and much more.

A general-purpose presentation of processors and their capabilities is available in the data processing documentation.

List dataset processors

List configured processors for a dataset. Please note that it reads in the order in which processors are applied.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Append a new processor

Create a new processor for the dataset. The processor will be appended to the end of the processing stack.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
type
required
string

Type of the processor

label
required
string

Friendly label of the processor

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "type": "string_replace",
  • "label": "replace old value with new value",
  • "field": "my_field",
  • "old": "old_value",
  • "new": "new_value"
}

Response samples

Content type
application/json
{
  • "uid": "pr_qf2hyt",
  • "type": "string_replace",
  • "label": "replace old value with new value",
  • "field": "my_field",
  • "old": "old_value",
  • "new": "new_value"
}

Retrieve dataset processor

Retrieve a dataset processor

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
processor_uid
required
string
Example: pr_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "pr_qf2hyt",
  • "type": "string_replace",
  • "label": "replace old value with new value",
  • "field": "my_field",
  • "old": "old_value",
  • "new": "new_value"
}

Update dataset processor

Update a processor in a dataset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
processor_uid
required
string
Example: pr_qf2hyt
Request Body schema: application/json
type
required
string

Type of the processor

label
required
string

Friendly label of the processor

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "type": "string_replace",
  • "label": "replace old value with new value",
  • "field": "my_field",
  • "old": "old_value",
  • "new": "new_value"
}

Response samples

Content type
application/json
{
  • "uid": "pr_qf2hyt",
  • "type": "string_replace",
  • "label": "replace old value with new value",
  • "field": "my_field",
  • "old": "old_value",
  • "new": "new_value"
}

Delete a dataset processor

Remove a processor from a dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
processor_uid
required
string
Example: pr_qf2hyt

Responses

Response samples

Content type
application/json
""

List processors

List all processors available on domain.

Authorizations:
QueryAPIKeyHeaderAPIKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Dataset feedbacks

The feedback feature allows users to suggest improvements to portal administrators. Feedback can either be about an existing record, or to request the addition of a new record in the dataset.

Feedback is an optional feature and is not activated on every Opendatasoft portal. Activation is done by a portal's administrators, and then has to be activated individually on each dataset.

List all dataset feedbacks

List all dataset feedbacks. Archived feedbacks aren't listed by default, use the is_archived parameter to query them.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
record_id
string

Find feedbacks made on a record with this id

is_archived
boolean
Default: 0

If true, list only archived feedbacks

sort
string
Default: "-created_at"
Example: sort=created_at

Sort by date of submission

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Retrieve a dataset feedback

Retrieve a dataset feedback

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
feedback_uid
required
string
Example: df_qf2hyt

Unique identifier for the feedback

Responses

Response samples

Content type
application/json
{
  • "uid": "df_qf2hyt",
  • "record_id": "95969ddab924fc5db5e39c3fb2a7634f4d7dd51c",
  • "user": {
    },
  • "comment": "I like this record, it provides meanigful insights",
  • "is_archived": false,
  • "values": {
    }
}

Archive a dataset feedback

Archive a dataset feedback

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
feedback_uid
required
string
Example: df_qf2hyt

Unique identifier for the feedback

Responses

Response samples

Content type
application/json
{
  • "uid": "df_qf2hyt",
  • "record_id": "95969ddab924fc5db5e39c3fb2a7634f4d7dd51c",
  • "user": {
    },
  • "comment": "I like this record, it provides meanigful insights",
  • "is_archived": false,
  • "values": {
    }
}

Dataset fields

Dataset fields can be configured using a variety of options. These options include their type, their label, whether they are a filter or not, whether they should be discarded, or even how fields are ordered.

These configuration options, collectively refered to as fields configuration, are accessed using processor-like objects.

Type of the field configuration:

  • rename - Fields are identified by a technical name, and have a human-friendly label; both are editable using this configuration item.
  • type - Types are the most basic way of qualifying fields. Different types unlock different kinds of visualizations and agregations. Below is the list of types supported by the platform.
  • annotate - Annotation are a mean to configure special behavior for the fields. Some annotations are only available for certain field types. Setting the facet annotation on a field unlocks other annotations for the field
  • description - Description are a mean to qualify and give some extra details about the content of the field. Descriptions are available when consulting the data.
  • order - Fields are processed and displayed in a definite order, this annotation can be used to change that order.
  • delete - Some fields present in the data source are not useful or redundant. This configuration item allows to discard them.

List dataset field configurations

List fields configurations for a dataset. Please note that it reads in the order in which processors are applied.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Append a new field configuration

Create a new field configuration for the dataset. The processor will be appended to the end of the fields configuration stack.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json

Create a field configuration in a dataset

type
required
string non-empty
label
required
string

Friendly label of the field configuration

from_name
required
string non-empty

The original technical identifier

to_name
required
string non-empty

The new technical identifier

field_label
required
string non-empty

A user friendly label for the field

Responses

Request samples

Content type
application/json
Example
{
  • "type": "rename",
  • "label": "Renaming field original_field_id",
  • "from_name": "original_field_id",
  • "to_name": "new_field_id",
  • "field_label": "New user friendly label"
}

Response samples

Content type
application/json
Example
{
  • "uid": "pr_qf2hyt",
  • "type": "rename",
  • "label": "Renaming field original_field_id",
  • "from_name": "original_field_id",
  • "to_name": "new_field_id",
  • "field_label": "New user friendly label"
}

Retrieve dataset field configuration

Retrieve a dataset field configuration

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
field_uid
required
string
Example: pr_qf2hyt

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "pr_qf2hyt",
  • "type": "rename",
  • "label": "Renaming field original_field_id",
  • "from_name": "original_field_id",
  • "to_name": "new_field_id",
  • "field_label": "New user friendly label"
}

Update dataset field configuration

Update a field configuration in a dataset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
field_uid
required
string
Example: pr_qf2hyt
Request Body schema: application/json
type
required
string non-empty
label
required
string

Friendly label of the field configuration

from_name
required
string non-empty

The original technical identifier

to_name
required
string non-empty

The new technical identifier

field_label
required
string non-empty

A user friendly label for the field

Responses

Request samples

Content type
application/json
Example
{
  • "type": "rename",
  • "label": "Renaming field original_field_id",
  • "from_name": "original_field_id",
  • "to_name": "new_field_id",
  • "field_label": "New user friendly label"
}

Response samples

Content type
application/json
Example
{
  • "uid": "pr_qf2hyt",
  • "type": "rename",
  • "label": "Renaming field original_field_id",
  • "from_name": "original_field_id",
  • "to_name": "new_field_id",
  • "field_label": "New user friendly label"
}

Destroy a field configuration

Remove a field configuration from a dataset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
field_uid
required
string
Example: pr_qf2hyt

Responses

Response samples

Content type
application/json
""

Dataset schedules

List dataset schedules

List dataset schedules

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create a dataset schedule

Create a dataset schedule

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: application/json
cron_schedule
required
string non-empty

The schedule using the unix-cron string format

Responses

Request samples

Content type
application/json
{
  • "cron_schedule": "0 * * * *"
}

Response samples

Content type
application/json
{
  • "uid": "sc_qf2hyt",
  • "cron_schedule": "0 * * * *"
}

Retrieve a dataset schedule

Retrieve a dataset schedule

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
schedule_uid
required
string
Example: sc_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "sc_qf2hyt",
  • "cron_schedule": "0 * * * *"
}

Update a dataset schedule

Update a dataset schedule

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
schedule_uid
required
string
Example: sc_qf2hyt
Request Body schema: application/json
cron_schedule
required
string non-empty

The schedule using the unix-cron string format

Responses

Request samples

Content type
application/json
{
  • "cron_schedule": "0 * * * *"
}

Response samples

Content type
application/json
{
  • "uid": "sc_qf2hyt",
  • "cron_schedule": "0 * * * *"
}

Delete a dataset schedule

Delete a dataset schedule

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
schedule_uid
required
string
Example: sc_qf2hyt

Responses

Response samples

Content type
application/json
""

Dataset versions

The versions of a dataset describe subsequent changes of states that affected the different sections of a dataset.

Every action taken on any resource through POST, PUT or DELETE creates a version object that can be retrieved and acted upon.

List all versions

List the dataset versions.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Retrieve version

Retrieve a dataset version.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
version_uid
required
string
Example: ch_qf2hyt
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "ch_qf2hyt",
  • "sections": [
    ],
  • "created_by": {
    },
  • "can_restore": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Restore version

Restores a dataset to the selected version. Restoring a version will not erase the versions history, but rather create a new version encapsulating the restoration.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
version_uid
required
string
Example: ch_qf2hyt
dataset_uid
required
string
Example: da_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "da_qf2hyt",
  • "dataset_id": "counties-united-states-of-america",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_published": false,
  • "is_restricted": true,
  • "metadata": {
    },
  • "default_security": {
    }
}

Dataset attachments

Dataset attachments are files that are exposed along with a dataset. These files help make sense of the data.

List dataset attachments

List all attachments to a dataset.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create dataset attachment

Create a dataset attachment

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "uid": "fromages.csv",
  • "filename": "fromages.csv",
  • "mimetype": "text/csv",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve dataset attachment

Retrieve a dataset attachment

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
attachment_uid
required
string
Example: at_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "fromages.csv",
  • "filename": "fromages.csv",
  • "mimetype": "text/csv",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete dataset attachment

Delete a dataset attachment

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
attachment_uid
required
string
Example: at_qf2hyt

Responses

Response samples

Content type
application/json
""

Download dataset attachment

Download the dataset attachment file

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
attachment_uid
required
string
Example: at_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "error_code": "not_found",
  • "message": "Not found."
}

Dataset alternative exports

Dataset alternative exports are custom dataset exports made outside the platform but available for end users to download like a normal export in the export menu.

Alternative exports are useful to expose exports in formats not supported by the platform, or in a specific geographic coordinate system. Alternative exports come in two types:

Uploaded File: This type of alternative export enables publishers to upload their own file one the platform. Since uploaded file alternative exports are static files instead of a dynamic exports, they tend to be very fast to download for end users and can be useful to offer a very large dataset export.

URL: This type allows publishers to provide a URL pointing to an external file that can be hosted outside the platform.

List dataset alternative exports

List dataset alternative exports

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create dataset alternative export

Create a dataset alternative export

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
Request Body schema: multipart/form-data
title
required
string non-empty
type
required
string
Value: "uploaded_file"
file
required
string <binary>
description
string

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "ae_mm8lbn",
  • "title": "Alternative export title",
  • "description": "Alternative export description",
  • "mimetype": "text/csv",
  • "type": "uploaded_file",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "filename": "fromages.csv"
}

Retrieve dataset alternative export

Retrieve a dataset alternative export

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
export_uid
required
string
Example: ae_qf2hyt

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "ae_mm8lbn",
  • "title": "Alternative export title",
  • "description": "Alternative export description",
  • "mimetype": "text/csv",
  • "type": "uploaded_file",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "filename": "fromages.csv"
}

Update dataset alternative export

Update a dataset alternative export

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
export_uid
required
string
Example: ae_qf2hyt
Request Body schema: application/json
title
required
string non-empty
type
required
string
Value: "uploaded_file"
description
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "type": "uploaded_file",
  • "description": "string"
}

Response samples

Content type
application/json
Example
{
  • "uid": "ae_mm8lbn",
  • "title": "Alternative export title",
  • "description": "Alternative export description",
  • "mimetype": "text/csv",
  • "type": "uploaded_file",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "filename": "fromages.csv"
}

Delete dataset alternative export

Delete a dataset alternative export

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
export_uid
required
string
Example: ae_qf2hyt

Responses

Response samples

Content type
application/json
""

Download dataset alternative export

Download the uploaded file alternative export or be redirected to the URL alternative export.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
dataset_uid
required
string
Example: da_qf2hyt
export_uid
required
string
Example: ae_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "error_code": "not_found",
  • "message": "Not found."
}

Harvesters

Harvesters provide a way for administrators to create and update an important number of datasets by importing them from an external source such as a CSW catalog or an ArcGIS service, among many others. Your user and your API key need the permissions create_dataset, edit_dataset and publish_dataset.

Through the Automation API, it is possible to:

  • create a harvester
  • start a harvester
  • publish the datasets attached to a harvester
  • unpublish the datasets attached to a harvester
  • delete a harvester and optionally delete its datasets

List harvesters

List the harvesters.

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create harvester

Create a harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
type
required
string non-empty
name
required
string non-empty
version
integer >= 1
Default: 1
restrict_datasets_visibility
boolean

If the harvested datasets should be configured as private. By default, it has the same value as the domain configuration "Restrict new datasets by default"

delete_missing_datasets
boolean
Default: false

If the source datasets are deleted on the harvested portal, delete them on this Opendatasoft portal too

object

Allow you to override some metadata in every harvested dataset

url
required
string non-empty
download_resources
boolean (download_resources)

If you want to download resources instead of attaching them via URL.

metadata_only
boolean (metadata_only)

If you want to harvest the remote datasets metadata without their resources.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "arcgis",
  • "name": "Harvester title",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Response samples

Content type
application/json
Example
{
  • "uid": "harvester-uid",
  • "type": "arcgis",
  • "name": "Harvester title",
  • "status": "idle",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "remote_datasets_count": 100,
  • "harvested_datasets_count": 98,
  • "published_datasets_count": 30,
  • "attached_datasets_count": 98,
  • "has_error": false,
  • "resource_errors_count": 2,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "last_started_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Retrieve harvester

Retrieve a harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "harvester-uid",
  • "type": "arcgis",
  • "name": "Harvester title",
  • "status": "idle",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "remote_datasets_count": 100,
  • "harvested_datasets_count": 98,
  • "published_datasets_count": 30,
  • "attached_datasets_count": 98,
  • "has_error": false,
  • "resource_errors_count": 2,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "last_started_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Update harvester

Update a harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
Request Body schema: application/json
type
required
string non-empty
name
required
string non-empty
version
integer >= 1
Default: 1
restrict_datasets_visibility
boolean

If the harvested datasets should be configured as private. By default, it has the same value as the domain configuration "Restrict new datasets by default"

delete_missing_datasets
boolean
Default: false

If the source datasets are deleted on the harvested portal, delete them on this Opendatasoft portal too

object

Allow you to override some metadata in every harvested dataset

url
required
string non-empty
download_resources
boolean (download_resources)

If you want to download resources instead of attaching them via URL.

metadata_only
boolean (metadata_only)

If you want to harvest the remote datasets metadata without their resources.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "arcgis",
  • "name": "Harvester title",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Response samples

Content type
application/json
Example
{
  • "uid": "harvester-uid",
  • "type": "arcgis",
  • "name": "Harvester title",
  • "status": "idle",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "remote_datasets_count": 100,
  • "harvested_datasets_count": 98,
  • "published_datasets_count": 30,
  • "attached_datasets_count": 98,
  • "has_error": false,
  • "resource_errors_count": 2,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "last_started_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Delete harvester

Delete the harvester. If delete_attached_datasets=true, also delete all its attached datasets.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
query Parameters
delete_attached_datasets
required
boolean

Control whether all attached datasets should be deleted with the harvester, or detached from it.

Responses

Response samples

Content type
application/json
""

Abort harvesting

Abort the harvesting of a harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "harvester-uid",
  • "type": "arcgis",
  • "name": "Harvester title",
  • "status": "idle",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "remote_datasets_count": 100,
  • "harvested_datasets_count": 98,
  • "published_datasets_count": 30,
  • "attached_datasets_count": 98,
  • "has_error": false,
  • "resource_errors_count": 2,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "last_started_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Start harvesting

Start a harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "harvester-uid",
  • "type": "arcgis",
  • "name": "Harvester title",
  • "status": "idle",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "remote_datasets_count": 100,
  • "harvested_datasets_count": 98,
  • "published_datasets_count": 30,
  • "attached_datasets_count": 98,
  • "has_error": false,
  • "resource_errors_count": 2,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "last_started_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Publish a harvester's datasets

Publish all datasets attached to the harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Unpublish a harvester's datasets

Unpublish all datasets attached to the harvester.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

List errors

List errors which occurred during the last or current harvesting.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
{
  • "harvester": "A fatal error occured. Please check the harvester configuration.",
  • "resources": {
    }
}

Preview harvesting

Preview the datasets which will be harvested.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
{
  • "total_count": 42,
  • "results": [
    ]
}

Preview harvesting configuration

Preview the datasets which will be harvested with a given configuration. At the contrary of the preview endpoint which returns the results for the currently saved harvester, this endpoint allows to preview the results with a configuration change not yet saved. The given parameters will be merged with the saved harvester configuration.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
Request Body schema: application/json
type
required
string non-empty
name
required
string non-empty
version
integer >= 1
Default: 1
restrict_datasets_visibility
boolean

If the harvested datasets should be configured as private. By default, it has the same value as the domain configuration "Restrict new datasets by default"

delete_missing_datasets
boolean
Default: false

If the source datasets are deleted on the harvested portal, delete them on this Opendatasoft portal too

object

Allow you to override some metadata in every harvested dataset

url
required
string non-empty
download_resources
boolean (download_resources)

If you want to download resources instead of attaching them via URL.

metadata_only
boolean (metadata_only)

If you want to harvest the remote datasets metadata without their resources.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "arcgis",
  • "name": "Harvester title",
  • "version": 1,
  • "restrict_datasets_visibility": true,
  • "delete_missing_datasets": false,
  • "forced_metas": {
    },
  • "url": "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services",
  • "download_resources": false,
  • "metadata_only": false
}

Response samples

Content type
application/json
{
  • "total_count": 42,
  • "results": [
    ]
}

Harvester schedules

Harvester schedules

List harvester schedules

List harvester schedules.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create harvester schedule

Create a harvester schedule. A harvester can only have one schedule.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
Request Body schema: application/json
cron_schedule
required
string non-empty

The schedule using the unix-cron string format

timezone
required
string non-empty

The schedule timezone

Responses

Request samples

Content type
application/json
{
  • "cron_schedule": "1 30 * * *",
  • "timezone": "Europe/Berlin"
}

Response samples

Content type
application/json
{
  • "uid": "sc_qf2hyt",
  • "cron_schedule": "1 30 * * *",
  • "timezone": "Europe/Berlin"
}

Retrieve a harvester schedule

Retrieve a harvester schedule.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
schedule_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
{
  • "uid": "sc_qf2hyt",
  • "cron_schedule": "1 30 * * *",
  • "timezone": "Europe/Berlin"
}

Update harvester schedule

Update a harvester schedule.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
schedule_uid
required
string
Example: harvester_uid
Request Body schema: application/json
cron_schedule
required
string non-empty

The schedule using the unix-cron string format

timezone
required
string non-empty

The schedule timezone

Responses

Request samples

Content type
application/json
{
  • "cron_schedule": "1 30 * * *",
  • "timezone": "Europe/Berlin"
}

Response samples

Content type
application/json
{
  • "uid": "sc_qf2hyt",
  • "cron_schedule": "1 30 * * *",
  • "timezone": "Europe/Berlin"
}

Delete harvester schedule

Delete a harvester schedule.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
harvester_uid
required
string
Example: harvester_uid
schedule_uid
required
string
Example: harvester_uid

Responses

Response samples

Content type
application/json
""

Users

A user is a person who authentifies themself to utilize the platform.

Most of the times, users are invited on a domain via an e-mail:

if the user doesn't have an Opendatasoft account, the e-mail provides them a link to create their account and choose a password,

this invitation links the new user or existing user to this domain, allowing domain administrators to grant them permissions to perform specific actions.

In other words, user accounts are shared between all Opendatasoft domains, but a user must be linked to a specific domain via an invitation before being granted specific permissions on this domain.

Through the Automation API, it is possible to:

  • list users linked to the domain,
  • lookup a specific user,
  • invite users on the domain (via an e-mail address),
  • grant users permissions, quotas and limits on the domain,
  • add or remove them from groups,
  • delete users from the domain.

List users

List users

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
search
string
Example: search=alice

full-text search among username, first name, last name and email

sort
Array of strings
Items Enum: "username" "first_name" "last_name" "last_seen_at"
Example: sort=username,first_name

sort results according to username, first name or last_name

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"
Example: permissions=edit_dataset&permissions=create_dataset

filter according to permissions granted directly to the users

all_permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"
Example: all_permissions=edit_dataset&all_permissions=create_dataset

filter according to permissions, whether granted directly or via a group

limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Retrieve user

Retrieve user

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
username
required
string
Example: louise.data
query Parameters
expand
string
Example: expand=groups

The list of fields to expand.

Responses

Response samples

Content type
application/json
{
  • "username": "louise.data",
  • "display_name": "louise.data",
  • "first_name": "Louise",
  • "last_name": "Data",
  • "is_active": true,
  • "email": "contact@email.com",
  • "is_ods": false,
  • "account_type": "global",
  • "permissions": [
    ],
  • "joined_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "expires_at": null,
  • "explore_limits": {
    },
  • "management_limits": { },
  • "gravatar_url": "//www.gravatar.com/avatar/6dde1de523fc80569f3dd80548e3eb9c?d=mm&s=80",
  • "groups": [
    ],
  • "identity_providers": [
    ]
}

Update user

Updates a user properties

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
username
required
string
Example: louise.data
Request Body schema: application/json
username
string

The user's username

first_name
string

The user's first name

last_name
string

The user's last name

email
required
string

The user's e-mail address

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to this user

object (ExploreLimits)

An object holding the user's quotas on this domain

management_limits
object (ManagementLimits)
Deprecated

An object holding the user's limits on this domain

Array of objects or Array of User group schema (objects)

A list of groups the user belongs to

Responses

Request samples

Content type
application/json
{
  • "username": "louise.data",
  • "first_name": "Louise",
  • "last_name": "Data",
  • "email": "contact@email.com",
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { },
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "username": "louise.data",
  • "display_name": "louise.data",
  • "first_name": "Louise",
  • "last_name": "Data",
  • "is_active": true,
  • "email": "contact@email.com",
  • "is_ods": false,
  • "account_type": "global",
  • "permissions": [
    ],
  • "joined_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "expires_at": null,
  • "explore_limits": {
    },
  • "management_limits": { },
  • "gravatar_url": "//www.gravatar.com/avatar/6dde1de523fc80569f3dd80548e3eb9c?d=mm&s=80",
  • "groups": [
    ],
  • "identity_providers": [
    ]
}

Delete user

Removes the requested user from the domain. If the user is the only domain administrator left, the call will fail and an error specifying that the removal of the only domain administrator is not allowed will be returned.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
""

Export users

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
subdomains
string

Subdomains to include in the CSV (requires the permission to export subdomains)

delimiter
string = 1 characters
Default: ","
Example: delimiter=;

Field separator

Responses

Response samples

Content type
text/csv
username,last_name,first_name,email,date_joined,last_seen,groups,permissions
louise.data,,,contact@mail.com,2022-08-19 11:43:58+00:00,2023-04-24 12:16:34.099404+00:00,Domain administrators;Data publishers,create_dataset;edit_dataset;explore_restricted_dataset;manage_dataset;publish_dataset

Invite users

This bulk endpoint creates an account for each of the given users and sends them an email so that they can log in. Each item in the payload must contain at least an email address, and may contain additional fields, such as groups and permissions. Returned body is an object in which each key is the number of the requested user in the payload ("0" = first user) and value contains a status_code ("success" or "error") and either "data" corresponding to the user or "error" describing the error.

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
Array
username
string

The user's username

first_name
string

The user's first name

last_name
string

The user's last name

email
required
string

The user's e-mail address

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to this user

object (ExploreLimits)

An object holding the user's quotas on this domain

management_limits
object (ManagementLimits)
Deprecated

An object holding the user's limits on this domain

Array of objects or Array of User group schema (objects)

A list of groups the user belongs to

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "01": {
    },
  • "02": {
    }
}

Provision users

This bulk endpoint creates an account for each of the given users using the given identity provider. Each item in the payload must contain at least an identity provider, and may contain additional fields, such as groups and permissions. Returned body is an object in which each key is the number of the requested user in the payload ("0" = first user) and value contains a status_code ("success" or "error") and either "data" corresponding to the user or "error" describing the error.

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
username
string

The user's username

first_name
string

The user's first name

last_name
string

The user's last name

email
required
string

The user's e-mail address

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to this user

object (ExploreLimits)

An object holding the user's quotas on this domain

management_limits
object (ManagementLimits)
Deprecated

An object holding the user's limits on this domain

Array of objects or Array of User group schema (objects)

A list of groups the user belongs to

required
object
identity_provider_attributes
object

Responses

Request samples

Content type
application/json
{
  • "username": "louise.data",
  • "first_name": "Louise",
  • "last_name": "Data",
  • "email": "contact@email.com",
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { },
  • "groups": [
    ],
  • "identity_provider": {
    },
  • "identity_provider_attributes": { }
}

Response samples

Content type
application/json
{
  • "01": {
    },
  • "02": {
    }
}

User groups

A group is an entity comprising several users. When users are added to a group, they benefit from the permissions, quotas and limits of this group.

Through the Automation API, the following can be performed on the current domain:

  • list groups,
  • lookup a specific group,
  • create groups,
  • grant groups permissions, quotas and limits,
  • list, add and delete users in groups,
  • delete groups

List user groups

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

search
string

full-text search among uid, title and description properties

sort
string
Default: "updated_at"
Enum: "created_at" "updated_at" "created_by__username" "updated_by__username" "user_count" "group__title"

sort results with respect to the specified properties.

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

filter groups according to the specified list of permissions

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
title
required
string

The group title

description
string

The group description

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to the members of this group

object (ExploreLimits)

An object holding the group's quotas on this domain

management_limits
object (ManagementLimits)
Deprecated

An object holding the group's limits on this domain

Responses

Request samples

Content type
application/json
{
  • "title": "Content Designers",
  • "description": "This wonderful group is for designers only.",
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { }
}

Response samples

Content type
application/json
{
  • "uid": "content_designers",
  • "title": "Content Designers",
  • "description": "This wonderful group is for designers only.",
  • "user_count": 42,
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_by": {
    }
}

Retrieve a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
{
  • "uid": "content_designers",
  • "title": "Content Designers",
  • "description": "This wonderful group is for designers only.",
  • "user_count": 42,
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_by": {
    }
}

Update a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
title
required
string

The group title

description
string

The group description

permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to the members of this group

object (ExploreLimits)

An object holding the group's quotas on this domain

management_limits
object (ManagementLimits)
Deprecated

An object holding the group's limits on this domain

Responses

Request samples

Content type
application/json
{
  • "title": "Content Designers",
  • "description": "This wonderful group is for designers only.",
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { }
}

Response samples

Content type
application/json
{
  • "uid": "content_designers",
  • "title": "Content Designers",
  • "description": "This wonderful group is for designers only.",
  • "user_count": 42,
  • "permissions": [
    ],
  • "explore_limits": {
    },
  • "management_limits": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_by": {
    }
}

Delete a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
""

List users of a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Add a user to a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
username
string

Responses

Request samples

Content type
application/json
{
  • "username": "louise.data"
}

Response samples

Content type
application/json
{
  • "username": "louise.data",
  • "display_name": "louise.data",
  • "first_name": "Louise",
  • "last_name": "Data",
  • "is_active": true,
  • "email": "contact@email.com",
  • "is_ods": false,
  • "account_type": "global",
  • "permissions": [
    ],
  • "joined_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "expires_at": null,
  • "explore_limits": {
    },
  • "management_limits": { },
  • "gravatar_url": "//www.gravatar.com/avatar/6dde1de523fc80569f3dd80548e3eb9c?d=mm&s=80",
  • "groups": [
    ],
  • "identity_providers": [
    ]
}

Batch add of users to a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
Array
username
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "01": {
    },
  • "02": {
    }
}

Remove a user from a user group

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
group_uid
required
string
Example: group_identifier
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
""

API keys

API keys are randomly generated passwords that can be used as an authentication method to access a protected API endpoint as an authorized user.

Through the Automation API, it is possible to list, create, lookup, update and delete API keys for one's own user.

List API keys

List API keys

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create an API key

Create an API key

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
label
string
permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to this API Key

Responses

Request samples

Content type
application/json
{
  • "label": "My API Key",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "uid": "ak_qf2hyt",
  • "label": "My API Key",
  • "key": "63d534ca0c1806024215cfd99dba4ea188f55d4f1b53ac0b6eceb455",
  • "permissions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "revocation_status": {
    },
  • "is_revoked": true
}

Retrieve an API key

Retrieve an API key

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
apikey_uid
required
string
Example: ak_qf2hyt
query Parameters
expand
string
Value: "user"

The list of fields to expand.

Responses

Response samples

Content type
application/json
{
  • "uid": "ak_qf2hyt",
  • "label": "My API Key",
  • "key": "63d534ca0c1806024215cfd99dba4ea188f55d4f1b53ac0b6eceb455",
  • "permissions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "revocation_status": {
    },
  • "is_revoked": true
}

Update an API key

Update an API key

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
apikey_uid
required
string
Example: ak_qf2hyt
Request Body schema: application/json
label
string
permissions
Array of strings (Permission)
Items Enum: "edit_domain" "create_page" "edit_page" "manage_page" "explore_restricted_page" "create_dataset" "edit_dataset" "publish_dataset" "manage_dataset" "explore_restricted_dataset" "edit_reuse" "manage_subdomains" "explore_monitoring" "edit_theme"

A list of permissions granted to this API Key

Responses

Request samples

Content type
application/json
{
  • "label": "My API Key",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "uid": "ak_qf2hyt",
  • "label": "My API Key",
  • "key": "63d534ca0c1806024215cfd99dba4ea188f55d4f1b53ac0b6eceb455",
  • "permissions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "revocation_status": {
    },
  • "is_revoked": true
}

Revoke an API key

Revoke an API key so that it is no longer valid. The reason for revocation can be provided.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
apikey_uid
required
string
Example: ak_qf2hyt
Request Body schema: application/json
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "Explanation why the API Key has been revoked"
}

Response samples

Content type
application/json
{
  • "uid": "ak_qf2hyt",
  • "label": "My API Key",
  • "key": "63d534ca0c1806024215cfd99dba4ea188f55d4f1b53ac0b6eceb455",
  • "permissions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "revocation_status": {
    },
  • "is_revoked": true
}

Search an API key

Domain administrators can search for a specific API key, revoked or active.

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
key
string

Responses

Request samples

Content type
application/json
{
  • "key": "63d534ca0c1806024215cfd99dba4ea188f55d4f1b53ac0b6eceb455"
}

Response samples

Content type
application/json
{
  • "found": true,
  • "result": {
    }
}

Datasources connections

List connections

List the datasources connections

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

sort
string
Default: "created_at"
Enum: "created_at" "updated_at" "type" "dataset_count"

Sort results with respect to the specified properties. You can prefix the property with the minus sign (-) for descending order, e.g. -created_at.

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create connection

Create a datasource connection

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
type
required
string non-empty
is_reusable
boolean

Defines if the connection can be reused across multiple datasets

url
required
string non-empty
Array of objects
HTTPAuth (object) or null

Responses

Request samples

Content type
application/json
Example
{
  • "type": "http",
  • "is_reusable": true,
  • "url": "https://my-server.com",
  • "headers": [
    ],
  • "auth": {
    }
}

Response samples

Content type
application/json
Example
{
  • "uid": "co_qf2hyt",
  • "type": "http",
  • "is_reusable": true,
  • "can_reuse": true,
  • "can_manage": true,
  • "dataset_count": 59,
  • "user_count": 7,
  • "group_count": 4,
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24",
  • "url": "https://my-server.com",
  • "headers": [
    ],
  • "auth": {
    }
}

Retrieve Connection

Retrieve a datasource connection

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt

Responses

Response samples

Content type
application/json
Example
{
  • "uid": "co_qf2hyt",
  • "type": "http",
  • "is_reusable": true,
  • "can_reuse": true,
  • "can_manage": true,
  • "dataset_count": 59,
  • "user_count": 7,
  • "group_count": 4,
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24",
  • "url": "https://my-server.com",
  • "headers": [
    ],
  • "auth": {
    }
}

Update Connection

Update a datasource connection. Datasets using this connection will be impacted, but won't be automatically republished.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
Request Body schema: application/json
type
required
string non-empty
is_reusable
boolean

Defines if the connection can be reused across multiple datasets

url
required
string non-empty
Array of objects
HTTPAuth (object) or null

Responses

Request samples

Content type
application/json
Example
{
  • "type": "http",
  • "is_reusable": true,
  • "url": "https://my-server.com",
  • "headers": [
    ],
  • "auth": {
    }
}

Response samples

Content type
application/json
Example
{
  • "uid": "co_qf2hyt",
  • "type": "http",
  • "is_reusable": true,
  • "can_reuse": true,
  • "can_manage": true,
  • "dataset_count": 59,
  • "user_count": 7,
  • "group_count": 4,
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24",
  • "url": "https://my-server.com",
  • "headers": [
    ],
  • "auth": {
    }
}

Delete Connection

Delete a datasource connection

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt

Responses

Response samples

Content type
application/json
""

Datasource connection security

List user rulesets

List the datasource connection user-level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create user ruleset

Create a datasource connection user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
Request Body schema: application/json
object (RelatedUser)

The user targeted by this ruleset.

permissions
Array of strings (PermissionEnum)
Items Value: "manage_connection"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Retrieve user ruleset

Retrieve a datasource connection user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Update user ruleset

Update a datasource connection user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
username
required
string
Example: louise.data
Request Body schema: application/json
object (RelatedUser)

The user targeted by this ruleset.

permissions
Array of strings (PermissionEnum)
Items Value: "manage_connection"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Delete user ruleset

Delete a datasource connection user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
""

List group rulesets

List the datasource connection group-level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create group ruleset

Create a datasource connection group-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
Request Body schema: application/json
object

The group targeted by this ruleset.

permissions
Array of strings (PermissionEnum)
Items Value: "manage_connection"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Retrieve group ruleset

Retrieve a datasource connection group-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Update group ruleset

Update a datasource connection group-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
object

The group targeted by this ruleset.

permissions
Array of strings (PermissionEnum)
Items Value: "manage_connection"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Delete group ruleset

Delete a datasource connection group-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
connection_uid
required
string
Example: co_qf2hyt
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
""

Studio pages

Studio is the new no-code editor that is designed to help you do just that: create and edit pages, built on your data, in only minutes.

Through the Automation API, it is possible to manage studio pages as well as to configure their visiblity on the portal.

List pages

List studio pages

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create page

Create a studio page

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
slug
string non-empty

Human-readable identifier used to generate the page URL

public
boolean
Default: false

Defines if the page is visible to a few specific users, or every user who can explore the portal

Responses

Request samples

Content type
application/json
{
  • "slug": "my-page",
  • "public": false
}

Response samples

Content type
application/json
{
  • "uid": "sp_qf2hyt",
  • "slug": "my-page",
  • "public": false,
  • "contents": [
    ],
  • "first_published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    }
}

Retrieve page

Retrieve a studio page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "uid": "sp_qf2hyt",
  • "slug": "my-page",
  • "public": false,
  • "contents": [
    ],
  • "first_published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    }
}

Update page

Update a studio page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
Request Body schema: application/json
slug
string non-empty

Human-readable identifier used to generate the page URL

public
boolean
Default: false

Defines if the page is visible to a few specific users, or every user who can explore the portal

Responses

Request samples

Content type
application/json
{
  • "slug": "my-page",
  • "public": false
}

Response samples

Content type
application/json
{
  • "uid": "sp_qf2hyt",
  • "slug": "my-page",
  • "public": false,
  • "contents": [
    ],
  • "first_published_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    }
}

Delete page

Delete a studio page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt

Responses

Response samples

Content type
application/json
""

Publish page

Publish a studio page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Unpublish page

Unpublish a studio page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Studio pages security

The page security is the set of rules that defines who (which users / groups) can explore or edit a given studio page.

It is defined through 2 variables:

  • a page restriction through the public attribute in the page object, which defines if a page is visible to every user who can explore the portal
  • specific rulesets for users and groups

If the page isn't set as public, then the page will only appear in the portal for users who have a ruleset declared for them, either directly or through a group. Other users won't have any access to the page.

Rulesets can also give users permission to edit the page.

List group rulesets

List the studio page group level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create group ruleset

Create a studio page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
Request Body schema: application/json
object

The group targeted by this ruleset.

permissions
Array of strings (PermissionEnum-3)
Items Value: "edit_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Retrieve group ruleset

Retrieve a studio page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Update group ruleset

Update a studio page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
object

The group targeted by this ruleset.

permissions
Array of strings (PermissionEnum-3)
Items Value: "edit_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Delete group ruleset

Delete a studio page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
""

List user rulesets

List the studio page user-level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create user ruleset

Create a studio page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
Request Body schema: application/json
object (RelatedUser)

The user targeted by this ruleset.

permissions
Array of strings (PermissionEnum-3)
Items Value: "edit_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Retrieve user ruleset

Retrieve a studio page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Update user ruleset

Update a studio page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
username
required
string
Example: louise.data
Request Body schema: application/json
object (RelatedUser)

The user targeted by this ruleset.

permissions
Array of strings (PermissionEnum-3)
Items Value: "edit_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Delete user ruleset

Delete a studio page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
studio_page_uid
required
string
Example: sp_qf2hyt
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
""

Code editor pages

Code editor pages can be used to write editorial content directly on the platform, build advanced dashboards and organize data portals.

Through the Automation API, it is possible to list, create, edit and delete code editor pages as well as to configure pages visiblity on the portal.

List pages

List code editor pages

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create page

Create a code editor page

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
slug
string

Human-readable identifier used to generate the page URL

object

Internationalized page title

description
string

Page description

required
object

Internationalized page content

template
string

The HTML template used by this page

tags
Array of strings

List of strings used to classify and sort pages

is_restricted
boolean

Defines if the page is visible to a few specific users, or every user who can explore the portal

is_archived
boolean

Defines if the page is archived. An archived page isn't included in the license quota, but can't be edited and isn't available to users.

Responses

Request samples

Content type
application/json
{
  • "slug": "hello_world",
  • "title": {
    },
  • "description": "A page saying hello",
  • "content": {
    },
  • "template": "custom.html",
  • "tags": [
    ],
  • "is_restricted": true,
  • "is_archived": false
}

Response samples

Content type
application/json
{
  • "slug": "hello_world",
  • "title": {
    },
  • "description": "A page saying hello",
  • "content": {
    },
  • "template": "custom.html",
  • "tags": [
    ],
  • "has_subdomain_copies": false,
  • "is_pushed_by_parent": false,
  • "is_restricted": true,
  • "is_archived": false,
  • "created_by": {
    },
  • "updated_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete multiple pages

Delete all code editor pages matching the search defined by the search and slug query parameters.

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
slug
Array of strings
Example: slug=slug1&slug=slug2

List of page slug to be removed.

search
string
Example: search=My Page Title

A search term to delete matching pages.

Responses

Response samples

Content type
application/json
[
  • "slug1",
  • "slug2"
]

Retrieve page

Retrieve a code editor page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug

Responses

Response samples

Content type
application/json
{
  • "slug": "hello_world",
  • "title": {
    },
  • "description": "A page saying hello",
  • "content": {
    },
  • "template": "custom.html",
  • "tags": [
    ],
  • "has_subdomain_copies": false,
  • "is_pushed_by_parent": false,
  • "is_restricted": true,
  • "is_archived": false,
  • "created_by": {
    },
  • "updated_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update page

Update a code editor page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
Request Body schema: application/json
slug
string

Human-readable identifier used to generate the page URL

object

Internationalized page title

description
string

Page description

required
object

Internationalized page content

template
string

The HTML template used by this page

tags
Array of strings

List of strings used to classify and sort pages

is_restricted
boolean

Defines if the page is visible to a few specific users, or every user who can explore the portal

is_archived
boolean

Defines if the page is archived. An archived page isn't included in the license quota, but can't be edited and isn't available to users.

Responses

Request samples

Content type
application/json
{
  • "slug": "hello_world",
  • "title": {
    },
  • "description": "A page saying hello",
  • "content": {
    },
  • "template": "custom.html",
  • "tags": [
    ],
  • "is_restricted": true,
  • "is_archived": false
}

Response samples

Content type
application/json
{
  • "slug": "hello_world",
  • "title": {
    },
  • "description": "A page saying hello",
  • "content": {
    },
  • "template": "custom.html",
  • "tags": [
    ],
  • "has_subdomain_copies": false,
  • "is_pushed_by_parent": false,
  • "is_restricted": true,
  • "is_archived": false,
  • "created_by": {
    },
  • "updated_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete page

Delete a code editor page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug

Responses

Response samples

Content type
application/json
""

Archive page

Archive a code editor page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Unarchive page

Unarchive a code editor page

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug

Responses

Response samples

Content type
application/json
{
  • "detail": "ok"
}

Code editor pages security

The page security is the set of rules that defines who (which users / groups) can explore or edit a given code editor page.

It is defined through 2 variables:

  • a page restriction through the is_restricted attribute in the page object, which defines if a page is visible to every user who can explore the portal
  • specific rulesets for users and groups

If the page is set as restricted, then the page will only appear in the portal for users who have a ruleset declared for them, either directly or through a group. Other users won't have any access to the page.

Rulesets can also give users permission to edit the page and manage its security.

List group rulesets

List the code editor page group level security rulesets

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create group ruleset

Create a code editor page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
Request Body schema: application/json
object

The group targeted by this ruleset.

permissions
Array of strings (PermissionEnum-2)
Items Enum: "edit_page" "manage_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Retrieve group ruleset

Retrieve a code editor page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Update group ruleset

Update a code editor page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
group_uid
required
string
Example: group_identifier
Request Body schema: application/json
object

The group targeted by this ruleset.

permissions
Array of strings (PermissionEnum-2)
Items Enum: "edit_page" "manage_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "permissions": [
    ]
}

Delete group ruleset

Delete a code editor page group level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
group_uid
required
string
Example: group_identifier

Responses

Response samples

Content type
application/json
""

List user rulesets

List the code editor page user-level permissions

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create user ruleset

Create a code editor page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
Request Body schema: application/json
object (RelatedUser)

The user targeted by this ruleset.

permissions
Array of strings (PermissionEnum-2)
Items Enum: "edit_page" "manage_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Retrieve user ruleset

Retrieve a code editor page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Update user ruleset

Update a code editor page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
username
required
string
Example: louise.data
Request Body schema: application/json
object (RelatedUser)

The user targeted by this ruleset.

permissions
Array of strings (PermissionEnum-2)
Items Enum: "edit_page" "manage_page"

List of special permissions granted to the target.

Responses

Request samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Delete user ruleset

Delete a code editor page user-level security ruleset

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
page_slug
required
string
Example: page_slug
username
required
string
Example: louise.data

Responses

Response samples

Content type
application/json
""

Assets

List image assets

List all domain assets urls

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create a new image asset

Add an asset to the library. The HTTP request must be a multipart request with a file property.

Authorizations:
QueryAPIKeyHeaderAPIKey

Responses

Response samples

Content type
application/json
{
  • "url": "/assets/theme_image/Acronym-Turquoise.svg"
}

Metadata templates

Metadata templates

List metadata templates

List all metadata templates of the current domain.

Authorizations:
QueryAPIKeyHeaderAPIKey
query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

is_active
boolean

If provided and True then it will list only all activated templates. If provided and False it lists non-activated templates. If not provided then it will lists both activated and non-activated templates.

type
string
Enum: "interop" "admin" "basic" "extra"

Filter by type of Metadata Template.

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Create metadata template

You can only create basic and admin metadata templates.

Authorizations:
QueryAPIKeyHeaderAPIKey
Request Body schema: application/json
name
required
string non-empty

Name (identifier) of the template

title
required
string

Title (description) of the template

is_active
required
boolean

True if the template is (needs to be) activated. False otherwise.

required
Array of objects (MetadataTemplateField)
type
required
string
Enum: "basic" "admin"

The type of the template. Only templates with type basic or admin can be created.

Responses

Request samples

Content type
application/json
{
  • "name": "my-custom-template",
  • "title": "My custom template",
  • "is_active": true,
  • "schema": [
    ],
  • "type": "basic"
}

Response samples

Content type
application/json
{
  • "name": "my-custom-template",
  • "title": "My custom template",
  • "is_active": true,
  • "is_always_active": false,
  • "is_system": false,
  • "schema": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "type": "basic"
}

Retrieve a metadata template

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
template_name
required
string
Example: template_name

Metadata template name

Responses

Response samples

Content type
application/json
{
  • "name": "my-custom-template",
  • "title": "My custom template",
  • "is_active": true,
  • "is_always_active": false,
  • "is_system": false,
  • "schema": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "type": "basic"
}

Update metadata template

Only non-system templates of type basic and admin can be fully editable. Other templates may be enabled. Templates with is_system=true and is_always_active=true are exceptions and can't be disabled.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
template_name
required
string
Example: template_name

Metadata template name

Request Body schema: application/json
name
required
string non-empty

Name (identifier) of the template

title
required
string

Title (description) of the template

is_active
required
boolean

True if the template is (needs to be) activated. False otherwise.

required
Array of objects (MetadataTemplateField)
type
required
string
Enum: "basic" "admin"

The type of the template. Only templates with type basic or admin can be created.

Responses

Request samples

Content type
application/json
{
  • "name": "my-custom-template",
  • "title": "My custom template",
  • "is_active": true,
  • "schema": [
    ],
  • "type": "basic"
}

Response samples

Content type
application/json
{
  • "name": "my-custom-template",
  • "title": "My custom template",
  • "is_active": true,
  • "is_always_active": false,
  • "is_system": false,
  • "schema": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": {
    },
  • "type": "basic"
}

Delete a metadata template

Only non-system templates of type basic or admin can be removed.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
template_name
required
string
Example: template_name

Metadata template name

Responses

Response samples

Content type
application/json
""

List template's fields

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
template_name
required
string
Example: template_name

Metadata template name

query Parameters
limit
number [ 0 .. 1000 ]
Default: 20
Example: limit=20

The maximum number of results returned by the API when the response is paginated. Tip: You can make a request with the parameter "limit" set to 0 to get only the metadata ("results" property will contain an empty array).

offset
number

The number of results to skip before beginning the listing in case of a paginated response

Responses

Response samples

Content type
application/json
{
  • "total_count": 18,
  • "next": null,
  • "previous": null,
  • "results": [
    ]
}

Retrieve metadata template field

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
template_name
required
string
Example: template_name

Metadata template name

template_field_name
required
string
Example: field_name

Metadata template field name

Responses

Response samples

Content type
application/json
{
  • "name": "my-custom-field",
  • "type": "text",
  • "label": "My custom field",
  • "help_text": null,
  • "is_hidden": false,
  • "self_suggest": false,
  • "is_filter": false,
  • "i18n": false,
  • "suggest_url": null,
  • "choices": null,
  • "labels": null,
  • "requirement_level": "optional"
}

Suggest field choices

List suggestions ("choices") for the provided template field name.

Authorizations:
QueryAPIKeyHeaderAPIKey
path Parameters
template_name
required
string
Example: template_name

Metadata template name

template_field_name
required
string
Example: field_name

Metadata template field name

query Parameters
query
required
string

The query to perform to the service providing the suggestions. Most likely, it will be a prefix of what you're looking for.

count
number

Number of results which will be provided in the response.

Responses

Response samples

Content type
application/json
{
  • "hits": [ ],
  • "nb_hits": 0,
  • "page": 0,
  • "hits_per_page": 0,
  • "exhaustive_nb_hits": true,
  • "exhaustive_typo": true,
  • "exhaustive": {
    },
  • "query": "string",
  • "params": "string",
  • "processing_time_ms": 0
}