Skip to content
Help

Sets API

The Sets API can be used to make groups of layers, tables and documents.

Set list

Section titled “Set list”
GET/sets/Lists sets

Returns a list of all the sets available to you.

This view shows all items within each set. If you don’t have permission to view an item within a set, its URL will still appear.

Response 200

Headers

Content-Type: application/json

Body

[{
    "id": 1,
    "title": "My collection",
    "description": "a collection of layers",
    "description_html": "<p>a collection of layers</p>",
    "categories": [],
    "tags": [],
    "user": {
        "id": 3,
        "name": "Bob Jones"
    },
    "items": [
        "https://{domain}/services/api/v1/layers/2/",
        "https://{domain}/services/api/v1/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1/sets/1/",
    "url_html": "https://{domain}/set/1-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": true,
    "permissions": "https://{domain}/services/api/v1/sets/1/permissions/",
    "created_at": "2012-12-19T23:13:26.324Z"
}]
POST/sets/Create a set

Required fields are:

  • Title
  • Description
  • Either group or user. This should be the ID or URL of the group or user you want to create the set for.

Other notable fields:

  • Items: A list of layers and/or documents specified using their urls. The order of this list will be used when rendering

Request

Headers

Content-Type: application/json

Body

{
    "title": "a collection",
    "description": "My favourite layers",
    "categories": [],
    "tags": [],
    "user": 3,
    "items": [
        "https://{domain}/services/api/v1/layers/2/",
        "https://{domain}/services/api/v1/layers/1/"
    ]
}

Response 201

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1/sets/123/

Body

{
    "id": 123,
    "title": "a collection",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "categories": [],
    "tags": [],
    "user": {
        "id": 3,
        "name": "Bob Jones"
    },
    "items": [
        "https://{domain}/services/api/v1/layers/2/",
        "https://{domain}/services/api/v1/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1/sets/123/",
    "url_html": "https://{domain}/set/123-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "permissions": "https://{domain}/services/api/v1/sets/123/permissions/",
    "created_at": "2015-05-12T21:54:21.276Z"
}

Set drafts

Section titled “Set drafts”
GET/sets/drafts/List sets in draft state

A filterable list views of set drafts, similar to /sets/. This view shows the draft version of each set. If the most recent version of a set has been published already, it won’t appear here.

All the same filters and ordering from sets/ apply.

Response 200

Body

[
    {
        "id": 3,
        "title": "Brand New Set",
        "url": "https://{domain}/services/api/v1.x/sets/3/",
        "type": "set",
        "created_at": "2020-05-19T04:25:07.220568Z"
    },
    {
        "id": 4,
        "title": "Other New Set",
        "url": "https://{domain}/services/api/v1.x/sets/4/",
        "type": "set",
        "created_at": "2020-05-19T04:25:07.220568Z"
    }
]

Set detail

Section titled “Set detail”
GET/sets/{id}/Get a set detail

This view displays the published version of a set. To get the draft version, hit /sets/{id}/versions/draft/

Response 200

Body

{
    "id": 1,
    "title": "My collection",
    "description": "a collection of layers",
    "description_html": "<p>a collection of layers</p>",
    "categories": [],
    "tags": [],
    "user": {
        "id": 3,
        "name": "Bob Jones"
    },
    "items": [
        "https://{domain}/services/api/v1/layers/2/",
        "https://{domain}/services/api/v1/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1/sets/1/",
    "url_html": "https://{domain}/set/1-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": true,
    "permissions": "https://{domain}/services/api/v1/sets/1/permissions/",
    "created_at": "2012-12-19T23:13:26.324Z"
}

Set versions

Section titled “Set versions”
GET/sets/{id}/versions/List set versions

Filterable list views of versions of a specific set, always sorted newest to oldest.

Response 200

Body

[
    {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
]
POST/sets/{id}/versions/Create a set version

Creates a new draft version of a set, accepting the same content as POST sets/.

Request

{
    "id": 2,
    "title": "a collection",
    "url": "https://{domain}/services/api/v1.x/sets/2/",
    "type": "set",
    "created_at": "2020-05-19T04:25:07.220568Z",
    "thumbnail_url": "",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "latest_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "published_version": null,
    "this_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "categories": [],
    "tags": [],
    "user": {
        "id": 1,
        "first_name": "Bob Jones",
    },
    "url_html": "https://{domain}/set/2/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "active_publish": null,
    "permissions": "https://{domain}/services/api/v1.x/sets/2/permissions/",
    "settings": {
        "lock_title_to_metadata": false,
        "lock_description_to_metadata": false,
        "lock_tags_to_metadata": false
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "version": {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
}

Response 201

Headers

Terminal window
Content-Type: application/json
Location: https://{domain}/services/api/v1/sets/1/versions/2/

Body

{}

Response 409

Headers

Terminal window
Content-Type: application/json
Location: https://{domain}/services/api/v1/sets/1/versions/2/

Body

{"error": "There is already a draft version active for this set."}

Set version

Section titled “Set version”
GET/sets/{id}/versions/{version}/Get set version

Get the details for a specific set version.

Response 200

Headers

{
    "id": 2,
    "title": "a collection",
    "url": "https://{domain}/services/api/v1.x/sets/2/",
    "type": "set",
    "created_at": "2020-05-19T04:25:07.220568Z",
    "thumbnail_url": "",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "latest_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "published_version": null,
    "this_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "categories": [],
    "tags": [],
    "user": {
        "id": 1,
        "first_name": "Bob Jones",
    },
    "url_html": "https://{domain}/set/2/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "active_publish": null,
    "permissions": "https://{domain}/services/api/v1.x/sets/2/permissions/",
    "settings": {
        "lock_title_to_metadata": false,
        "lock_description_to_metadata": false,
        "lock_tags_to_metadata": false
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "version": {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
}
PUT/sets/{id}/versions/{version}/Edit set version

Edits this set version. If the set is already published, a 405 response will be returned. Accepts same fields as GET above, , but ignores the version object.

Response 200

Headers

{
    "id": 2,
    "title": "a collection with updated data",
    "url": "https://{domain}/services/api/v1.x/sets/2/",
    "type": "set",
    "created_at": "2020-05-19T04:25:07.220568Z",
    "thumbnail_url": "",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "latest_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "published_version": null,
    "this_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "categories": [],
    "tags": [],
    "user": {
        "id": 1,
        "first_name": "Bob Jones",
    },
    "url_html": "https://{domain}/set/2/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "active_publish": null,
    "permissions": "https://{domain}/services/api/v1.x/sets/2/permissions/",
    "settings": {
        "lock_title_to_metadata": false,
        "lock_description_to_metadata": false,
        "lock_tags_to_metadata": false
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "version": {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
}

Response 405

Headers

{"error": "This version isn't a draft."}
DELETE/sets/{id}/versions/{version}/Delete a set version

Deletes this draft version (revert to published).

Response 204

{}

Response 405

{"error": "This version isn't a draft."}

Response 409

{"error": "This version is already deleted."}

Publish set version

Section titled “Publish set version”
POST/sets/{id}/versions/{version}/publish/Publish set version

Creates a publish task just for this set version

No POST data.

PUT/sets/{id}/Update a set

The following fields are editable (other fields will be ignored):

  • title
  • description
  • categories
  • tags
  • user / group
  • items (note: existing items will be removed if they’re not specified here)

Request

Headers

Content-Type: application/json

Body

{
    "description": "Important Layers"
}

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "title": "My collection",
    "description": "Important Layers",
    "description_html": "<p>Important Layers</p>",
    "categories": [],
    "tags": [],
    "user": {
        "id": 3,
        "name": "Bob Jones"
    },
    "items": [
        "https://{domain}/services/api/v1/layers/2/",
        "https://{domain}/services/api/v1/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1/sets/1/",
    "url_html": "https://{domain}/set/1-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": true,
    "permissions": "https://{domain}/services/api/v1/sets/1/permissions/",
    "created_at": "2012-12-19T23:13:26.324Z"
}
DELETE/sets/{id}/Delete a set

Delete this set.

Response 204