Admin API recipes: update a layer, set auto-update, delete a draft, page through results

These recipes combine endpoints from the Layers & tables API and the Sources API. They apply to customer sites. The examples use $APITOKEN for your API key and {domain} for your site’s domain. The key needs the scopes named in each recipe. See Set scopes for an API token. Replace the IDs with your own.

Update a layer from a new upload

This recipe replaces a layer’s data with a new file. It needs the sources:write and layers:write scopes.

1. Upload the new file as a source

   Create an upload source with a multipart request. The scan starts automatically. See the Sources API. The response’s Location header is the new source’s URL, for example /sources/3/, and its last_scan field is the URL of the scan the upload started, for example /sources/3/scans/4/. For large files, use presigned uploads and start the scan yourself: the Location header of POST /sources/3/scans/ is the scan’s URL.

2. Wait for the scan, then find the new datasource

   Poll the scan URL from the previous step (GET /sources/3/scans/4/) until its status is completed. Then list the source’s datasources, GET /sources/3/datasources/, and note the id of the datasource for your file.

   curl 'https://{domain}/services/api/v1.x/sources/3/datasources/' \
     -H "Authorization: key $APITOKEN" \
     -H 'Accept: application/json'

3. Create a new version of the layer that uses it

   POST to /layers/123/versions/ with the datasource, and a reference that says what changed. A new draft is created, and the import starts straight away.

   curl -X POST 'https://{domain}/services/api/v1.x/layers/123/versions/' \
     -H "Authorization: key $APITOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"reference": "Q4 update", "data": {"datasources": [{"id": 345}]}}'

   The response is 201, with the new draft’s URL in the Location header. If the layer already has a draft, you get 409 instead: see Delete a draft.

4. Wait for the import

   Poll the version, GET /layers/123/versions/789/, until its status is ok. A status of importing means it’s still running, and progress shows how far it has got.

5. Publish the version

   POST /layers/123/versions/789/publish/. This creates a publish task that publishes as soon as any import is complete.

To create, import and publish in one call, POST the same body to /layers/123/versions/publish/. It returns 409 if the layer already has a draft. To create a draft and always start an import, use /layers/123/versions/import/.

Turn on scheduled updates

A scheduled update checks the layer’s connected source on a schedule and publishes new data. It’s the same setting as the Scheduled Updates tab in the Data Manager. See Why didn’t my layer update automatically?.

Set the layer’s autoupdate object with a PUT to its settings. You need the layers:write scope and administer access to the layer.

curl -X PUT 'https://{domain}/services/api/v1.x/layers/123/settings/' \
  -H "Authorization: key $APITOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"autoupdate": {"behavior": "yes-noschema", "schedule": "0 14 * * * Pacific/Auckland", "force_autoupdate": false}}'

Field	Values
behavior	no turns scheduled updates off. yes-noschema updates when new data is available, except when columns have been added or removed. yes-always also continues when the columns change.
schedule	A cron expression of five fields and an optional time zone name. Minutes are ignored, so use 0. Use null when behavior is no. The Scheduled Updates tab sets a daily, weekly or monthly time on the hour.
force_autoupdate	true carries on updating even if an errored draft exists. It’s the Continue to update if an errored draft exists switch.

To turn scheduled updates off, send {"autoupdate": {"behavior": "no", "schedule": null, "force_autoupdate": false}}.

You can also send autoupdate when you create a layer. The layer’s autoupdate object in the layer detail shows the current setting. If it shows behavior as not-applicable, the layer can’t have scheduled updates.

These rules apply:

• Only vector and table layers made from a single connected source can have scheduled updates. A layer made from an upload can’t. Setting a schedule on another layer returns an error.
• A schedule is required when behavior isn’t no.
• Some plans limit how many layers can have a schedule. If you’ve reached your limit, the request is refused with limit-reached and a message that names the limit.

Delete a draft

A layer can have only one draft. If you try to create a second one, the API returns 409:

{"already-exists": "This layer already has a draft version"}

The Location header of that response is the existing draft’s URL. You can also find it at /layers/123/versions/draft/, which redirects to the draft and returns 404 if there isn’t one.

To throw the draft away and go back to the published version, DELETE it:

curl -X DELETE 'https://{domain}/services/api/v1.x/layers/123/versions/234/' \
  -H "Authorization: key $APITOKEN"

A successful delete returns 204. If the version isn’t a draft, the API returns 405 with {"not-draft": "This version isn't a draft, so you can't delete it"}. A published version can’t be deleted this way. Then create your new version again. See also Delete, restore and clean up revisions.

If the draft failed to import, you can instead PUT the draft with the corrected data to cancel the import and start a new one, or POST to /layers/123/versions/234/import/ to start the import again.

Page through list results

List endpoints return one page at a time. Use page for the page number and page_size for the number of records per page.

curl -i 'https://{domain}/services/api/v1.x/layers/123/versions/?page=2&page_size=50' \
  -H "Authorization: key $APITOKEN" \
  -H 'Accept: application/json'

Every list response has two headers:

• X-Paginate-By: the maximum records per page.
• X-Resource-Range: the records in this response, as start-end/total. For example, 0-50/120 means the first 50 of 120 records.

Some lists also send a Link header with page-next, page-previous and page-last links. Follow page-next until it’s missing. The standard maximum page size is 200. Asking for more returns an error that says the page size must be 200 or less. Some endpoints differ, so check the X-Paginate-By header. See Introducing the Admin API.

For long lists of versions, add data_import=true to leave out versions that only changed details, or send the header Expand: list to get each version’s change summary.