Workspaces¶

10 operations in the Adverity Connect API. Replace {{INSTANCE}} and {{KEY}} in the examples with your instance and API key. How authentication works.

List stacks¶

GET/api/stacks/

API key permissionWorkspace: Read-onlyworkspace:read

Query parameters

namestring
orderingstring
Which field to use when ordering the results.
pageinteger
A page number within the paginated result set.
page_sizeinteger
Number of results to return per page.
uuidstring · uuid

Responses

200OKapplication/json

Response schema

object PaginatedStackList

countintegerrequired
Example 123
nextstring · urinullable
Example "http://api.example.org/accounts/?page=4"
previousstring · urinullable
Example "http://api.example.org/accounts/?page=2"
resultsarray of objectrequired
Items · Stack
- add_connection_urlstringrequiredread-only
- add_datastream_urlstringrequiredread-only
- change_urlstringrequiredread-only
- datalakestring · urirequiredread-only
- destinationinteger
- extracts_urlstringrequiredread-only
- issues_urlstringrequiredread-only
- idintegerrequiredread-only
- uuidstring · uuidrequiredread-only
- namestringrequired
  Max length 60
- overview_urlstringrequiredread-only
- parentstring · urirequiredread-only
- parent_idinteger
- slugstringrequiredread-only
- urlstring · urirequiredread-only
- countsstringrequiredread-only
- permissionsstringrequiredread-only
- default_manage_extract_namesboolean
  This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
- email_cobranding_enabledboolean
- email_cobranding_logo_urlstring · uri
  Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
  Max length 2000
- email_cobranding_display_namestring
  Displays if your brand logo isn't available.
  Max length 255
- updatedstring · date-timerequiredread-only
- createdstring · date-timerequiredread-only

RequestcURL

curl --request GET 'https://{{INSTANCE}}/api/stacks/' \
  --header 'Authorization: Bearer {{KEY}}'

Response200

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "add_connection_url": "string",
      "add_datastream_url": "string",
      "change_url": "string",
      "datalake": "https://example.com",
      "destination": 1,
      "extracts_url": "string",
      "issues_url": "string",
      "id": 1,
      "uuid": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "overview_url": "string",
      "parent": "https://example.com",
      "parent_id": 1,
      "slug": "string",
      "url": "https://example.com",
      "counts": "string",
      "permissions": "string",
      "default_manage_extract_names": true,
      "email_cobranding_enabled": true,
      "email_cobranding_logo_url": "https://example.com",
      "email_cobranding_display_name": "string",
      "updated": "2024-01-01T00:00:00Z",
      "created": "2024-01-01T00:00:00Z"
    }
  ]
}

Create stacks¶

POST/api/stacks/

API key permissionWorkspace: Writeworkspace:write

Request bodyrequired

application/json also application/x-www-form-urlencoded, multipart/form-data

Body schema

object Stack

datalake_idintegerrequiredwrite-only
destinationinteger
namestringrequired
Max length 60
parent_idinteger
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255

Responses

201Createdapplication/json

Response schema

object Stack

add_connection_urlstringrequiredread-only
add_datastream_urlstringrequiredread-only
change_urlstringrequiredread-only
datalakestring · urirequiredread-only
destinationinteger
extracts_urlstringrequiredread-only
issues_urlstringrequiredread-only
idintegerrequiredread-only
uuidstring · uuidrequiredread-only
namestringrequired
Max length 60
overview_urlstringrequiredread-only
parentstring · urirequiredread-only
parent_idinteger
slugstringrequiredread-only
urlstring · urirequiredread-only
countsstringrequiredread-only
permissionsstringrequiredread-only
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255
updatedstring · date-timerequiredread-only
createdstring · date-timerequiredread-only

RequestcURL

curl --request POST 'https://{{INSTANCE}}/api/stacks/' \
  --header 'Authorization: Bearer {{KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "datalake_id": 1,
    "destination": 1,
    "name": "string",
    "parent_id": 1,
    "default_manage_extract_names": true,
    "email_cobranding_enabled": true,
    "email_cobranding_logo_url": "https://example.com",
    "email_cobranding_display_name": "string"
  }'

Response201

{
  "add_connection_url": "string",
  "add_datastream_url": "string",
  "change_url": "string",
  "datalake": "https://example.com",
  "destination": 1,
  "extracts_url": "string",
  "issues_url": "string",
  "id": 1,
  "uuid": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "overview_url": "string",
  "parent": "https://example.com",
  "parent_id": 1,
  "slug": "string",
  "url": "https://example.com",
  "counts": "string",
  "permissions": "string",
  "default_manage_extract_names": true,
  "email_cobranding_enabled": true,
  "email_cobranding_logo_url": "https://example.com",
  "email_cobranding_display_name": "string",
  "updated": "2024-01-01T00:00:00Z",
  "created": "2024-01-01T00:00:00Z"
}

Get stacks¶

GET/api/stacks/{slug}/

API key permissionWorkspace: Read-onlyworkspace:read

Path parameters

slugstringrequired

Responses

200OKapplication/json

Response schema

object Stack

add_connection_urlstringrequiredread-only
add_datastream_urlstringrequiredread-only
change_urlstringrequiredread-only
datalakestring · urirequiredread-only
destinationinteger
extracts_urlstringrequiredread-only
issues_urlstringrequiredread-only
idintegerrequiredread-only
uuidstring · uuidrequiredread-only
namestringrequired
Max length 60
overview_urlstringrequiredread-only
parentstring · urirequiredread-only
parent_idinteger
slugstringrequiredread-only
urlstring · urirequiredread-only
countsstringrequiredread-only
permissionsstringrequiredread-only
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255
updatedstring · date-timerequiredread-only
createdstring · date-timerequiredread-only

RequestcURL

curl --request GET 'https://{{INSTANCE}}/api/stacks/{slug}/' \
  --header 'Authorization: Bearer {{KEY}}'

Response200

{
  "add_connection_url": "string",
  "add_datastream_url": "string",
  "change_url": "string",
  "datalake": "https://example.com",
  "destination": 1,
  "extracts_url": "string",
  "issues_url": "string",
  "id": 1,
  "uuid": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "overview_url": "string",
  "parent": "https://example.com",
  "parent_id": 1,
  "slug": "string",
  "url": "https://example.com",
  "counts": "string",
  "permissions": "string",
  "default_manage_extract_names": true,
  "email_cobranding_enabled": true,
  "email_cobranding_logo_url": "https://example.com",
  "email_cobranding_display_name": "string",
  "updated": "2024-01-01T00:00:00Z",
  "created": "2024-01-01T00:00:00Z"
}

Replace stacks¶

PUT/api/stacks/{slug}/

API key permissionWorkspace: Writeworkspace:write

Path parameters

slugstringrequired

Request bodyrequired

application/json also application/x-www-form-urlencoded, multipart/form-data

Body schema

object Stack

datalake_idintegerrequiredwrite-only
destinationinteger
namestringrequired
Max length 60
parent_idinteger
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255

Responses

200OKapplication/json

Response schema

object Stack

add_connection_urlstringrequiredread-only
add_datastream_urlstringrequiredread-only
change_urlstringrequiredread-only
datalakestring · urirequiredread-only
destinationinteger
extracts_urlstringrequiredread-only
issues_urlstringrequiredread-only
idintegerrequiredread-only
uuidstring · uuidrequiredread-only
namestringrequired
Max length 60
overview_urlstringrequiredread-only
parentstring · urirequiredread-only
parent_idinteger
slugstringrequiredread-only
urlstring · urirequiredread-only
countsstringrequiredread-only
permissionsstringrequiredread-only
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255
updatedstring · date-timerequiredread-only
createdstring · date-timerequiredread-only

RequestcURL

curl --request PUT 'https://{{INSTANCE}}/api/stacks/{slug}/' \
  --header 'Authorization: Bearer {{KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "datalake_id": 1,
    "destination": 1,
    "name": "string",
    "parent_id": 1,
    "default_manage_extract_names": true,
    "email_cobranding_enabled": true,
    "email_cobranding_logo_url": "https://example.com",
    "email_cobranding_display_name": "string"
  }'

Response200

{
  "add_connection_url": "string",
  "add_datastream_url": "string",
  "change_url": "string",
  "datalake": "https://example.com",
  "destination": 1,
  "extracts_url": "string",
  "issues_url": "string",
  "id": 1,
  "uuid": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "overview_url": "string",
  "parent": "https://example.com",
  "parent_id": 1,
  "slug": "string",
  "url": "https://example.com",
  "counts": "string",
  "permissions": "string",
  "default_manage_extract_names": true,
  "email_cobranding_enabled": true,
  "email_cobranding_logo_url": "https://example.com",
  "email_cobranding_display_name": "string",
  "updated": "2024-01-01T00:00:00Z",
  "created": "2024-01-01T00:00:00Z"
}

Update stacks¶

PATCH/api/stacks/{slug}/

API key permissionWorkspace: Writeworkspace:write

Path parameters

slugstringrequired

Request body

application/json also application/x-www-form-urlencoded, multipart/form-data

Body schema

object PatchedStack

datalake_idintegerwrite-only
destinationinteger
namestring
Max length 60
parent_idinteger
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255

Responses

200OKapplication/json

Response schema

object Stack

add_connection_urlstringrequiredread-only
add_datastream_urlstringrequiredread-only
change_urlstringrequiredread-only
datalakestring · urirequiredread-only
destinationinteger
extracts_urlstringrequiredread-only
issues_urlstringrequiredread-only
idintegerrequiredread-only
uuidstring · uuidrequiredread-only
namestringrequired
Max length 60
overview_urlstringrequiredread-only
parentstring · urirequiredread-only
parent_idinteger
slugstringrequiredread-only
urlstring · urirequiredread-only
countsstringrequiredread-only
permissionsstringrequiredread-only
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255
updatedstring · date-timerequiredread-only
createdstring · date-timerequiredread-only

RequestcURL

curl --request PATCH 'https://{{INSTANCE}}/api/stacks/{slug}/' \
  --header 'Authorization: Bearer {{KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "datalake_id": 1,
    "destination": 1,
    "name": "string",
    "parent_id": 1,
    "default_manage_extract_names": true,
    "email_cobranding_enabled": true,
    "email_cobranding_logo_url": "https://example.com",
    "email_cobranding_display_name": "string"
  }'

Response200

{
  "add_connection_url": "string",
  "add_datastream_url": "string",
  "change_url": "string",
  "datalake": "https://example.com",
  "destination": 1,
  "extracts_url": "string",
  "issues_url": "string",
  "id": 1,
  "uuid": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "overview_url": "string",
  "parent": "https://example.com",
  "parent_id": 1,
  "slug": "string",
  "url": "https://example.com",
  "counts": "string",
  "permissions": "string",
  "default_manage_extract_names": true,
  "email_cobranding_enabled": true,
  "email_cobranding_logo_url": "https://example.com",
  "email_cobranding_display_name": "string",
  "updated": "2024-01-01T00:00:00Z",
  "created": "2024-01-01T00:00:00Z"
}

Delete stacks¶

DELETE/api/stacks/{slug}/

API keyNot supportedThis operation needs a signed-in Adverity user, so a Connect API key cannot call it. Use the Adverity app to do this.

Path parameters

slugstringrequired

Responses

204No response body

Get stacks schema¶

GET/api/stacks/{slug}/schema/

API key permissionWorkspace: Read-onlyworkspace:read

Export the target field schema configured for this workspace.

Path parameters

slugstringrequired

Responses

200OKapplication/json

Response schema

object StackSchema

target_columnsarray of objectrequired
Items · StackSchemaTargetColumn
- namestringrequired
  Max length 200
- typeintegerrequired
  - 1 - String (dimension)
  - 2 - Long (metric, whole number)
  - 3 - Float (metric, decimal number)
  - 4 - Date (dimension, YYYY-MM-DD)
  - 5 - DateTime (dimension, YYYY-MM-DDTHH:MM:SS)
  - 6 - Boolean (dimension, usually "true" and "false")
  - 7 - Percentage (metric, fraction as %)
  - 9 - Currency (metric)
  - 8 - JSON (JSON-compatible format)
  - 10 - Formula (expression sent to Google Sheets Destination)
  - 11 - Duration (expression of time duration)
  - 13 - Timestamp (dimension, YYYY-MM-DDTHH:MM:SS±HH:MM, converted to UTC)
  One of 1 2 3 4 5 6 7 9 8 10 11 13
- lengthintegernullable
  Min -2147483648 · Max 2147483647
- measureone of
  Attributes
  - MeasureEnum
  - NullEnum
- descriptionstring
- default_mappingarray of objectrequired
  Items · StackSchemaDefaultMapping
  - source_column_typestringrequired
    Natural key, e.g. 'core.apidatastream'.
    Pattern ^\w+\.\w+$
  - source_column_namestringrequired
  - is_key_columnbooleanrequired

Create stacks schema¶

POST/api/stacks/{slug}/schema/

API key permissionWorkspace: Writeworkspace:write

Import a target field schema. Existing target fields are updated in place and fields absent from the payload are left untouched.

Path parameters

slugstringrequired

Query parameters

resetboolean
Re-point existing per-datastream column mappings in this workspace to the imported target fields. Defaults to false.

Request bodyrequired

application/json

Body schema

object StackSchema

target_columnsarray of objectrequired
Items · StackSchemaTargetColumn
- namestringrequired
  Max length 200
- typeintegerrequired
  - 1 - String (dimension)
  - 2 - Long (metric, whole number)
  - 3 - Float (metric, decimal number)
  - 4 - Date (dimension, YYYY-MM-DD)
  - 5 - DateTime (dimension, YYYY-MM-DDTHH:MM:SS)
  - 6 - Boolean (dimension, usually "true" and "false")
  - 7 - Percentage (metric, fraction as %)
  - 9 - Currency (metric)
  - 8 - JSON (JSON-compatible format)
  - 10 - Formula (expression sent to Google Sheets Destination)
  - 11 - Duration (expression of time duration)
  - 13 - Timestamp (dimension, YYYY-MM-DDTHH:MM:SS±HH:MM, converted to UTC)
  One of 1 2 3 4 5 6 7 9 8 10 11 13
- lengthintegernullable
  Min -2147483648 · Max 2147483647
- measureone of
  Attributes
  - MeasureEnum
  - NullEnum
- descriptionstring
- default_mappingarray of objectrequired
  Items · StackSchemaDefaultMapping
  - source_column_typestringrequired
    Natural key, e.g. 'core.apidatastream'.
    Pattern ^\w+\.\w+$
  - source_column_namestringrequired
  - is_key_columnbooleanrequired

Responses

200OKapplication/json

Response schema

object StackSchemaImportResult

statusstringrequired
messagestringrequired

400Malformed schema payload or invalid reset value.

415Content-Type other than application/json.

Get stacks stats¶

GET/api/stacks/{slug}/stats/

API key permissionWorkspace: Read-onlyworkspace:read

Path parameters

slugstringrequired

Responses

200OKapplication/json

Response schema

object Stack

add_connection_urlstringrequiredread-only
add_datastream_urlstringrequiredread-only
change_urlstringrequiredread-only
datalakestring · urirequiredread-only
destinationinteger
extracts_urlstringrequiredread-only
issues_urlstringrequiredread-only
idintegerrequiredread-only
uuidstring · uuidrequiredread-only
namestringrequired
Max length 60
overview_urlstringrequiredread-only
parentstring · urirequiredread-only
parent_idinteger
slugstringrequiredread-only
urlstring · urirequiredread-only
countsstringrequiredread-only
permissionsstringrequiredread-only
default_manage_extract_namesboolean
This setting is used as the default for new datastreams. You can still change this setting for individual datastreams in the Local data retention settings.
email_cobranding_enabledboolean
email_cobranding_logo_urlstring · uri
Publicly-accessible HTTPS URLs only. Recommended at least 64 px high PNG, transparent background.
Max length 2000
email_cobranding_display_namestring
Displays if your brand logo isn't available.
Max length 255
updatedstring · date-timerequiredread-only
createdstring · date-timerequiredread-only

RequestcURL

curl --request GET 'https://{{INSTANCE}}/api/stacks/{slug}/stats/' \
  --header 'Authorization: Bearer {{KEY}}'

Response200

{
  "add_connection_url": "string",
  "add_datastream_url": "string",
  "change_url": "string",
  "datalake": "https://example.com",
  "destination": 1,
  "extracts_url": "string",
  "issues_url": "string",
  "id": 1,
  "uuid": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "overview_url": "string",
  "parent": "https://example.com",
  "parent_id": 1,
  "slug": "string",
  "url": "https://example.com",
  "counts": "string",
  "permissions": "string",
  "default_manage_extract_names": true,
  "email_cobranding_enabled": true,
  "email_cobranding_logo_url": "https://example.com",
  "email_cobranding_display_name": "string",
  "updated": "2024-01-01T00:00:00Z",
  "created": "2024-01-01T00:00:00Z"
}

List Workspaces¶

GET/api/v1/workspaces/

API key permissionWorkspace: Read-onlyworkspace:read

Query parameters

pageinteger
Default 1 · Min 1
page_sizeinteger
Default 50 · Min 1

Responses

200OKapplication/json

Response schema

object PagedWorkspaceResponseSchema

itemsarray of objectrequired
Items · WorkspaceResponseSchema
- idstring · uuidrequired
- parent_idstring · uuidnullable
  Attributes
  - string · uuid
  - null
- namestringrequired
  Max length 60
countintegerrequired