{ "openapi": "3.0.0", "info": { "version": "1.0.1", "title": "Koordinates API Documentation", "license": { "name": "Koordinates API Terms of Use", "url": "https://koordinates.com/terms-of-use/" }, "x-logo": { "url": "./logo-400x200.png" }, "description": "Documentation for Koordinates REST APIs.\n# Getting started\n## Introduction\nKoordinates provides a RESTful API that uses standard HTTP methods and status codes. This documentation provides detailed developer documentation for specific API endpoints, including request and response formats. This should be read in conjunction with the Help documentation available at https://help.koordinates.com/\n## Authentication\nThere are a number of ways to authenticate with the Koordinates API depending on your requirements. Note that not every method is available for every endpoint. Supported authentication methods are listed under in endpoint's \"Authorization\" section.\nRefer to API Tokens documentation for creating and modifying tokens.\nMost endpoints require the API token to carry a particular scope. Every response includes an `Accepted-OAuth-Scopes` header naming the scope the endpoint requires (`*` if none), and requests authenticated with a token also get an `OAuth-Scopes` header listing the scopes that token holds. A token lacking the required scope gets a `401` whose `detail` names the missing scope.\n\n## API Features\n### Pagination\nList APIs are paginated with two query parameters:\n\n - `page` - the page to return, 1-based. Defaults to `1`.\n - `page_size` - the number of items per page. Defaults to `100`. Most\n endpoints cap it at `200`; the group, license, version-datasource,\n version-tile and datasource link-resolution lists allow up to `100000`.\n Asking for more than the cap is a `400`.\n\nList API responses will include pagination headers.\n\n - `X-Paginate-By` - the number of items per page\n - `X-Resource-Range` - the range of items in the current response in the form `start-end/total`\n\nFor example:\n\n ```\n X-Paginate-By: 20\n X-Resource-Range: 20-40/320\n ```\n\n### Searching and filtering\nSearch-backed list APIs - `/data/`, `/layers/`, `/tables/`, `/items/` and `/sources/` - share one set of query parameters, documented on `/data/`. Filters that take several values are repeated (`?tag=a&tag=b`) and OR-ed together; different filters are AND-ed.\n`q` is a free-text search over each item's title, description, tags, category and geotag names, plus its publisher's name, its field names and (for sets) its member layers. An item matches if it matches *any* term; items matching more terms rank higher, and title matches are weighted most heavily. With `q` and no `sort`, results are ordered by relevance.\nQuery parameters the endpoint does not recognise are ignored rather than rejected, so a misspelt filter returns an unfiltered list. Recognised parameters with invalid values are a `400`.\n### Faceting\nSearch-backed list APIs - the ones that accept `q` and a `sort` order, such as `/data/`, `/layers/`, `/items/`, `/sources/` and `/groups/` - also accept `facets=true`. This replaces the result list with the facet counts for the filters already applied, so a client can show how many results each remaining choice would return.\nWhich facets come back depends on what the matching objects populate; possible keys are `tag`, `group`, `geotag`, `category`, `license`, `raster_resolution` and `raster_band`. Each entry carries the value to filter by (`key`) and the number of results it would return (`total`). For example:\n\n ```\n GET /services/api/v1.x/data/?kind=layer&facets=true\n\n {\n \"geotag\": [\n {\n \"key\": \"global/oceania/new-zealand\",\n \"name\": \"New Zealand\",\n \"total\": 4021,\n \"has_children\": true,\n \"geom\": null\n },\n ...\n ],\n \"category\": [\n {\"key\": \"cadastral\", \"name\": \"Cadastral\", \"total\": 812},\n ...\n ]\n }\n ```\n\nFacet counts always cover the whole result set, whatever `page` and `page_size` say. Add `geotag.geometry=true` to include the selected geotag's geometry in the `geotag` facets.\n### Link Headers\nList APIs that can be sorted or paged will usually include Link headers that conform to the [RFC 5988](https://tools.ietf.org/html/rfc5988) standard.\nFor example:\n ```\n Link:\n ; rel=\"page-next\",\n ; rel=\"page-last\",\n ; rel=\"sort-name\",\n ; rel=\"sort-name-desc\",\n ; rel=\"sort-most-popular\",\n ; rel=\"sort-recently-added\",\n ; rel=\"sort-recently-updated\",\n ; rel=\"sort-recently-featured\",\n ; rel=\"sort-recently-featured-oldest-first\"\n ```\n\n### Expansions\nExpansions (sometimes known as “side-loads”) provide a way to include related content into a particular API view. For many property values, we supply a URL to the resource. For example:\n\n {\n \"id\": 4,\n \"url\": \"https://{domain}/services/api/v1/layers/1/\",\n \"type\": \"layer\",\n \"name\": \"Road Centerlines\",\n \"permissions\": \"https://{domain}/services/api/v1/layers/4/permissions/\",\n ...\n\n The permissions property points to a URL where we can see the permissions\n for this layer. We can include the permissions response directly in this\n request by including an Expand header with the value permissions.\n\n Expand: permissions\n\n More than one expansion can be requested by providing property names\n separated by commas.\n\n A list of available expansions for any particular view is accessible\n via an `OPTIONS` request. This will return an object that contains the\n key expansions and an array of valid expansion options. For example:\n\n {\n \"name\": \"Layer Detail\",\n \"expansions\": [\n \"permissions\"\n ]\n }\n\n Some list views can provide more detailed responses via the special list\n expansion. Note that list expansions cannot be used in conjunction with detailed item expansions.\n" }, "servers": [ { "url": "https://{domain}/services/api/v{version}", "variables": { "domain": { "default": "koordinates.com", "description": "Production API service" }, "version": { "enum": [ "1", "1.x" ], "default": "1.x" } } } ], "tags": [ { "name": "Data Management Overview", "x-displayName": "Overview", "description": "The following APIs are used to connect to external services, import and manage publication of data on the Koordinates platform.\n### Concepts\n#### Sources, Data Sources and Scans\nA **Source** is a container of data that we can potentially process. Examples of Sources include:\n\n * An uploaded Zip containing many pieces of data\n * An internet-accessible WFS server or Esri AGOL service account\n * A connected S3 bucket\n\nA **Data Source** is a specific file, service or resource in a **Source** that could be ingested into the Koordinates platform. Some examples of data sources include:\n\n * A particular shapefile in an uploaded Zip\n * A specific layer in a WFS (Web Feature Service) or Esri AGOL account\n * A single GeoTIFF in an AWS S3 bucket\n\nData sources are discovered by Koordinates by running a **Scan**. This is a process where we inspect the source to find the available data sources, and make them availale for importing. Some sources, like an upload, only need to be scanned once. Other sources, like an S3 bucket, can be regularly scanned to find new, updated or removed data sources.\n### Importing Data\nData sources are used to create **Layers**, **Tables** and **Documents**. This is typically done by creating a new object and providing refences to the **data sources** discovereed in a **scan**.\n\n * **Layers** and **Tables** can be created from one or more data sources. If more than one data source is used they must be of the\n same data type (e.g. vector polyon, geotiff, etc) and have the same schema (columns, field types, number of bands, etc).\n\n * **Documents** can only be created form a single data source and only if its a file-like datasource.\n\n * **Sets** are created from other Layers and Tables, rather than from data sources.\n\n### Versions and Publishing\nLayers, Tables, Documents and Sets are versioned.\n\n * The **published** version is the currently visible version to users. Exports of the item will include data from the\n published version. Published versions cannot be edited. To modify an item, a new **draft** version is created.\n * The **draft** version, if it exists, can be modified. New data can also be imported to the draft version. Once edits\n to the draft are complete the draft can be **published**.\n" }, { "name": "Catalog Items", "description": "A **catalog item** is a catalog entry that links to a resource — either\nhosted on a Koordinates site or elsewhere. A catalog item usually has one\nor more **services** attached, which is how the linked resource is\naccessed (for example 3D Tiles, WMTS or WFS). Each item is addressed by a\npublic ID prefixed with `c` (for example `c3TRfmHwdwpc9QY`).\n\n### Versions\n\nCatalog items are versioned. The **published** version is visible to\nusers; the **draft** version, if it exists, can be edited and then\npublished. See the [Data Management Overview](#tag/Data-Management-Overview) for how versioning and\npublishing work across the platform.\n\n### Sub-resources\n\nEach catalog item version exposes a number of sub-resources:\n\n * **Metadata** in ISO, FGDC and Dublin Core (`dc`) formats, plus\n simplified representations.\n * **Attachments** — supporting documents attached to the item.\n * **Vector styles**, **geotags**, and consumer actions such as\n **star**, **pin**, **request-access** and **feedback**.\n\n### Services\n\nEach catalog item exposes the data services configured for it (WMTS,\nWFS, exports, etc.). See the [Services documentation](#tag/Services) to list,\nenable/disable, and manage permissions on these services.\n\nDraft editing, publishing, deletion and permission management\nendpoints are administrative.\n" }, { "name": "Categories" }, { "name": "Coordinate Systems", "description": "The Coordinate Systems API provides simple CRS lookup and search for the\ncoordinate systems supported by the Koordinates platform.\n" }, { "name": "Data Object Identifiers", "description": "DOIs – or Data Object Identifiers – are unique addresses assigned to a piece of\ndigital content. They are intended to provide a persistent link to its location\non the internet. Koordinates supports manually assigned DOIs and supports DOI\n\"minting\" and integrated management with the [DataCite](https://datacite.org/)\nregistry service.\n\nFor sites that have this feature enabled, the Data Object Identifiers API is\nan extension to Layer, Table and Document APIs. For more information about enabling\nData Object Identifier support to your site, please contact support@koordinates.com.\n\n### DOI Representations\n\nDOIs can be defined in the following ways:\n\n * As a basic prefix/suffix of the form `10.5072/FK2SJ1J03K`\n * As a URL `https://doi.org/10.5072/FK2SJ1J03K`\n * As a name-spaced DOI string `doi:10.5072/FK2SJ1J03K`\n\nAny of these forms is considered an acceptable way to supply DOI strings to the API.\nYou can also supply one or more of these in an object keyed by url or identifier as\nlong as they are equivalent.\n" }, { "name": "Data Catalog", "description": "The `/data/` endpoints search the whole catalog - layers, tables, sets,\ndocuments, Kart repositories, map viewers and catalog items - and define\nthe filter parameters shared by every search-backed list. See\n*Searching and filtering* in the introduction.\n" }, { "name": "Data Sources", "description": "The Data Sources API provides read and write access to sources, datasources and scans.\n\n### Source-specific notes\nThere are several types of sources. Each exposes the same set of core fields, but some fields are only exposed or accepted for specific types of sources. Everything in `options` is optional.\n\n### CIFS, URL, ArcGIS, and WFS source options\nAll these source types can accept credentials in an `options` field:\n\n* `options`:\n * `username` : username to access this server.\n * `password` : password for this server.\n * `ssl_verify` : A boolean specifying whether Koordinates should verify the SSL certificate of the host when scanning this source. Defaults to true.\nUsername and password are write-only. They are never returned to clients via the API.\n\n### ArcGIS Server\n* `url_remote` : The URL of your ArcGIS server, usually ending with/rest/api/services/. Must not contain credentials.\n\n* `options` : In addition to the options listed above, ArcGIS also accepts:\n\n * `folders` : A JSON array of folders to scan. If not given, the whole server will be scanned.\n\n### CIFS\n* `url_remote` : A URL of the form \"cifs://host/sharename\", optionally with extra path segments. Must not contain credentials.\n\n### PostgreSQL\n* `url_remote` : A URL of the form \"postgresql://host:port/database\". Must not contain credentials.\n\n* `options` :\n\n * `username` : username to access the PostgreSQL database.\n * `password` : postgres database password.\n * `schemas` : A JSON array containing schema names, e.g.: `\"schemas\": [\"public\", \"other_schema\"]`\n\n### URL\nA URL source defines an FTP, HTTP or HTTPS url to an archive Koordinates can scan for data.\n\nCurrently accepts these archives:\n\n* .zip\n* .tar.gz, .tgz\n* .7z\n\nURL sources accept the following extra fields:\n* `url_remote` : The URL to download the archive. Must not contain credentials.\n\n### WFS Server\n* `url_remote` : The URL to the WFS server endpoint. Must not contain credentials.\n" }, { "name": "Documents", "description": "Document API" }, { "name": "Exports", "description": "The Export API provides methods for extracting data in bulk from the Koordinates platform. Multiple layers can be exported in one download, data can be cropped, reprojected into different coordinate reference systems, and data can be exported in many different formats.\n" }, { "name": "Groups" }, { "name": "Layers", "x-displayName": "Layers & Tables", "description": "Layer APIs" }, { "name": "Licenses" }, { "name": "Notifications", "description": "Publishes, scans and exports run asynchronously. Rather than polling their status endpoints, subscribe to the notification stream and be told when they finish.\n" }, { "name": "Pinning" }, { "name": "Raster Query", "description": "The Raster Query API allows users to request information related to a point location from one or more Koordinates grid or raster datasets.\n\n### URL\nYour URL endpoint is dependent on the particular Koordinates service you wish to access.\n\nThe URL for the Koordinates.com will be: `https://koordinates.com/services/query/v1/raster`\n\nThe raster query API returns in JSON:\n\n`content-type: application/vnd.koordinates.rasterQuery+json`\nFormats can be specified via URL. For example: `https://koordinates.com/services/query/v1/raster.json`\n\nThey can also be specified using the HTTP Accept header with the appropriate content-type against the base URL. For example: `application/vnd.koordinates.rasterQuery.1+json`.\n\nBy default, all responses use the newest format. While we try very hard to prevent backwards-incompatible breaks, please note that it may happen in future.\n\nIf you're using the URL endpoint (for example, `rasterQuery.json`) you can pass a &v=1 parameter to specify version 1. Note that the current version is 1.\n\n### Compression\nAdd a request header with `Accept-Encoding: gzip` to get compressed results. This dramatically reduces the size of the response and will speed up your API requests.\n" }, { "name": "Repositories", "description": "The Repositories API allows you to create and interact with hosted Kart repositories. Refer to\nhttps://KartProject.org for more information on Kart.\n" }, { "name": "Services", "description": "The Services API allows you to configure which data services are enabled\nand who can access them. Each service is attached to an _Owner_ — a\nlayer, table, set (collection), or catalog item.\n\n## Service types\n\nEach service has a stable `key` (used as the `key` field and as\n`service_id` in service URLs). Services are attached to an _Owner_ — a\nlayer, table, set (collection), or catalog item. Owner-type columns\nindicate where each service can appear.\n\n| Key | Name | What it does | Owners |\n|-----|------|--------------|--------|\n| `kart` | Kart Repository | Git-based version-controlled repository (Kart mirror) for a layer. | layer |\n| `csw` | Catalog Service for the Web | OGC CSW endpoint for metadata discovery. | layer, set, catalog-item |\n| `spatial-query-grid` | Raster Query API | Spatial query API for raster/grid data. | layer |\n| `spatial-query-tiles` | Raster Tiles Query API | Spatial query over raster tile data (no user API access required). | layer |\n| `spatial-query-vector` | Vector Query API | Latitude/longitude spatial queries over vector data. | layer |\n| `spatial-query-set` | Set Query API | Spatial query across all layers in a set. | set |\n| `data-table` | Data Table API | Tabular feature and raster-tile queries. | layer |\n| `wfs` | OGC Web Feature Service | WFS for vector and table data retrieval. | layer |\n| `wfs-changesets` | WFS Changesets | WFS for retrieving changesets from version-controlled layers. | layer |\n| `tiles` | OGC Web Map Tile Service (WMTS) | Tiled map imagery via WMTS. Exposes `tilegrids` and `styles`. | layer, set |\n| `esri-map` | Esri Map Service | Map tiles in Esri format. May be unavailable depending on plan/site settings. | layer, set, catalog-item |\n| `wmts` | OGC WMTS Map Service | Map tiles in OGC WMTS format. | layer, set, catalog-item |\n| `vector-tile-pmtiles` | ProtoMaps Vector Tile (PMTiles) | Vector tiles in PMTiles format for efficient streaming. | layer |\n| `vector-tile-mvt` | Mapbox Vector Tile (MVT) | Vector tiles in Mapbox MVT format. | layer |\n| `vector-tile-mbtiles` | MBTiles Vector Tile | Vector tiles in MBTiles database format. | layer |\n| `vector-tile-arcgis` | ArcGIS Vector Tile Service | Vector tiles for ArcGIS VectorTileServer. | layer |\n| `vector-tile-json` | Vector Tile JSON | Vector tile metadata in TileJSON format. | layer, set, catalog-item |\n| `raster-pmtile` | Raster ProtoMaps Tile (PMTiles) | Raster tiles in PMTiles format. | layer, set, catalog-item |\n| `raster-tile-json` | Raster Tile JSON | Raster tile metadata in TileJSON format. | layer, set, catalog-item |\n| `copc` | Cloud Optimized Point Cloud (COPC) | COPC format for LiDAR/point-cloud data. | layer |\n| `esri-rest-api` | Esri REST Services | Esri-compatible REST query/retrieval API. | layer |\n| `3d-tiles` | OGC 3D Tiles | Streamable 3D meshes/models (photogrammetry, buildings, point clouds). | layer |\n| `ifc` | Industry Foundation Classes (IFC) | IFC open standard for building/construction data. | layer, set, catalog-item |\n| `kart-diff` | Kart Diff | Differences between Kart commits. | layer, set, catalog-item |\n| `export` | Export Service | Export layer data in various formats. | layer |\n| `small-data` | Small Data File | Direct download of small data files. | catalog-item |\n| `external` | External Service | User-defined external service attached to a viewer or dataset. Adds `kind: \"external\"` and a `description` field. | layer, set, catalog-item, repo-dataset |\n\n### UI-only service types (internal)\n\nThe following service types do not deliver data; they only control web-app\nUI visibility and are internal, web-app visibility only:\n`kart-ui`, `spatial-query-ui`, `data-table-ui`,\n`vector-tile-pmtiles-ui`, `copc-ui`.\n\n### Configurable Services\n\nThe services which can be enabled/disabled, and have their permissions\nedited inherit permissions from their owner as follows:\n\n - If a user/group has `download` permissions on a layer, by default they will have `access` to the following services:\n - `kart`\n - `export`\n - `wfs` and `wfs-changesets`\n - If a user/group has `view` permissions on a layer, by default they will have `access` to the following services:\n - `tiles`\n - `data-table`\n - `spatial-query-vector`, `spatial-query-tiles`, and `spatial-query-grid`\n\nIf a service isn't listed above, it cannot be enabled/disabled or have its\npermissions edited via this API.\n\n### Listing services\n\nServices are owned by layers, tables, sets and catalog items. List them on\nthe Service List endpoint for the relevant owner:\n\n`/services/api/{api_version}/layers/{layer_id}/services/`\n`/services/api/{api_version}/sets/{set_id}/services/`\n`/services/api/{api_version}/items/{catalogitem_id}/services/`\n\nSee the [Catalog Items documentation](#tag/Catalog-Items) for catalog-item services.\n\n### Disabling / Enabling services\nEnable/disable the service with a PUT request `{\"enabled\": true|false}` to the Service Detail endpoint:\n\n`/services/api/{api_version}/layers/{layer_id}/services/{service_id}/`\n\n### Service permissions\n\nThe Service Permissions view lists which users/groups have been granted `access` permissions over a Service:\n\n`/services/api/{api_version}/layers/{layer_id}/services/{service_id}/permissions/`\n\nBy default, this endpoint will return an empty list, which means service permissions are inherited from their\nowner following the rules described above under _Configurable Services_.\n\nBut if groups/users are listed, they are the only roles who can use the service. The one exception are users who have `admin`\npermissions over the Service Owner. They will still be able to `access` the service, even if they are not listed on the\nService Permissions view.\n\nTo update which groups/users have permissions over a service, supply them in a PUT request:\n\n```\n[{\"group\": 123, \"permission\": \"access\"}, {\"group\": 456, \"permission\": \"access\"}]\n```\n\nAny groups/users supplied here must also have the requisite permission on the owner per _Configurable Services_\nto use the service. For example, you could give a group `access` to a WFS Service, but if they don't have\n`download` permissions over its layer, they won't be able to utilise the service.\n\n### Checking user/group access against a service\n\nIf you want to check whether a specific user or group has `access` over a service, do a GET request to the Check Permissions\nendpoint:\n\n`/services/api/{api_version}/layers/{layer_id}/services/{service_id}/permissions/{user|group}.{user_id|group_id|group_alias}/access/`\n\n### External services\n\nIn addition to the built-in service types, you can expose layers and\ntables through **external** (third-party) services hosted outside the\nKoordinates platform. This is a two-step process: a site administrator\ndefines a reusable **external service template**, then external services\nare attached to individual datasets from that template. The external\nservices feature must be enabled on your site by Koordinates; contact\nsupport to request it (there is no API to enable it or to check whether it\nis enabled). While it is disabled, the endpoints below return `404 Not\nFound`; if you are authenticated but not a site administrator they return\n`403 Forbidden`.\n\n**1. Create a template** (site administration rights required):\n\n`POST /services/api/{api_version}/site/external-service-templates/`\n\nA template's `template_urls` field holds one to three entries, each with a\n`service_url` (and an optional `name`). The `scope` field controls which\ndataset types the template can be attached to. Within a `service_url`, the\ntokens `{id}`, `{shortname}` and `{title}` are replaced, when a service is\nattached, with the target **dataset's** ID, short name and title\nrespectively (these refer to the dataset being attached to — not the\ntemplate's own `short_name` field). Any other text — including tile\nplaceholders such as `{z}/{x}/{y}` — is left unchanged. For example:\n\n```\n{\n \"title\": \"Aerial Imagery Basemap\",\n \"short_name\": \"aerial-basemap\",\n \"description\": \"Aerial imagery basemap (WebMercatorQuad WebP tiles).\",\n \"template_urls\": [\n {\"name\": \"Aerial tiles\", \"service_url\": \"https://tiles.example.com/v1/aerial/WebMercatorQuad/{z}/{x}/{y}.webp?api=YOUR_API_KEY\"}\n ],\n \"scope\": [\"all\"],\n \"enabled\": true,\n \"access_policy\": \"all-users\"\n}\n```\n\nThe response includes the new template's `id`. List, update and delete\ntemplates under the same path.\n\n**2. Attach external services** to a layer or table (requires `admin` on\nthe dataset). Repeat this for each dataset you want to expose, passing the\n`id` of the template from step 1:\n\n`POST /services/api/{api_version}/{layers|tables}/{layer_id}/external-services/`\n\n```\n{\"template_id\": 42, \"enabled\": true}\n```\n\nThe attached service is returned in the same form as built-in services\n(its `id`, e.g. `s3YPf…`, is used in the detail URL below). Manage each\nexternal service (enable/disable, delete) on its detail endpoint:\n\n`/services/api/{api_version}/{layers|tables}/{layer_id}/external-services/{service_id}/`\n" }, { "name": "Set Query", "description": "The Set Query API allows users to look up a point location and get back information from a set.\n\nA set is a collection of data layers and tables that can be viewed downloaded at one time. Publishers use sets to enable users to access datasets that are commonly grouped together.\n\n### Differences to vector and raster APIs\nThe set query API returns similar information to the Vector and Raster API endpoints, with a few notable differences\n\n* You query a single set, not a number of layers. You don't have to know what layers are in the set before you query it.\n* Layers are returned in the correct order, in a JSON list rather than an object. Both vector and grid layers from the set will be included.\n* Each layer returned contains its ID and title, since you might not already have them.\n### URL\nYour URL endpoint is dependent on the particular Koordinates service you wish to access.\n\nThe URL for the Koordinates site will be `https://koordinates.com/services/query/v1/set`\n### Formats\nThe sets API returns in JSON:\n\ncontent-type: application/vnd.koordinates.setQuery+json\n\nFormats can be specified via URL. For example: `http://api.koordinates.com/api/setQuery.json`\n\nThey can also be specified using the HTTP Accept header with the appropriate content-type against the base URL. For example: application/vnd.koordinates.rasterQuery.1+json\n\nBy default, all responses use the newest format. While we try very hard to prevent backwards-incompatible breaks, please note that it may happen in future\n\nIf you're using the URL endpoint (for example, rasterQuery.json) you can pass a &v=1 parameter to specify version 1.3. Note that the current version is 1.3\n\n### Compression\nAdd a request header with Accept-Encoding: gzip to get compressed results. This dramatically reduces the size of the response and will speed up your API requests.\n" }, { "name": "Sites" }, { "name": "Users", "description": "User APIs" }, { "name": "Vector Query", "description": "The Vector Query API allows users to request information related to a point location from one or more Koordinates vector datasets.\n\n### URL\n\nYour URL endpoint is dependent on the particular Koordinates service you wish to access.\n\nThe URL for Koordinates.com site will be: `https://koordinates.com/services/query/v1/vector.json`\n\n\n### Compression\nAdd a request header with `Accept-Encoding: gzip` to get compressed results. This dramatically reduces the size of the response and will speed up your API requests.\n" } ], "paths": { "/groups/": { "get": { "summary": "List Groups", "description": "Get the groups configured for this site.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getGroups", "parameters": [ { "name": "q", "in": "query", "description": "Free-text search query", "required": false, "schema": { "type": "string" } }, { "name": "access_requests_enabled", "in": "query", "description": "Filter groups with or without access requests", "required": false, "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "description": "Filter by group type (repeatable). `normal` covers ordinary groups, including the site default group; `members` is the organisation members group.\n", "required": false, "schema": { "type": "string", "enum": [ "normal", "members" ] } }, { "name": "sort", "in": "query", "description": "Sort order. Defaults to relevance.", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "popularity", "created_at", "-created_at", "updated_at", "-updated_at" ] } }, { "name": "facets", "in": "query", "description": "Return facet counts for the current filters instead of results - see [Faceting](#section/Getting-started/API-Features).\n", "required": false, "schema": { "type": "boolean" } }, { "name": "Expand", "in": "header", "required": false, "description": "`list` returns the full group representation for each result instead of the summary one. `list.permissions` additionally inlines each group's permissions (requires the `edit_users` permission on the group; without it the field stays a URL).\n", "schema": { "type": "string", "enum": [ "list", "list.permissions" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGroups" } } } } } } }, "/groups/{group_id}/": { "get": { "summary": "Get a Group.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getGroupById", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "Expand", "in": "header", "required": false, "description": "`permissions` inlines the group's permissions instead of linking to them. Requires the `edit_users` permission on the group; without it the field stays a URL.\n", "schema": { "type": "string", "enum": [ "permissions" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } } } } }, "/groups/{group_id}/permissions/": { "get": { "summary": "List Group User Permissions", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "security", "in": "query", "description": "Filter by account security type.", "required": false, "schema": { "type": "string", "enum": [ "mfa", "remote_auth", "verified" ] } } ], "description": "Returns a list of permissions granted to users within this group.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getGroupPermissions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUserPermissionList" } } } } } }, "patch": { "summary": "Modify Group User Permissions", "description": "Allows the caller to make multiple changes to the group permissions. Each action in the list has one of three `action` types that can be performed:\n\n * `create` - add a new permission for a user to this group\n * `update` - modify the permissions for an existing permission\n * `delete` - delete a permission that currently exists\n\nThe `update` and `delete` operations require the `url` to the permission as returned in the `GET` request to this endpoint.\nThe `value` object specifies the `user` (by ID) and the permission to grant.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "patchGroupPermissions", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchGroupUserPermissionListRequest" } } } }, "responses": { "204": { "description": "NO CONTENT" }, "409": { "description": "CONFLICT - A user already belongs to group" } } }, "post": { "summary": "Add Group User Permissions", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "postGroupPermissions", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutPostGroupUserPermission" } } } }, "responses": { "201": { "description": "NO CONTENT" }, "409": { "description": "CONFLICT - A user already belongs to group" } } } }, "/groups/{group_id}/permissions/user.{user_id}/": { "get": { "summary": "Get User Group Permission", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getGroupUserPermission", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "user_id", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUserPermission" } } } }, "404": { "description": "NOT FOUND" } } }, "put": { "summary": "Update User Group Permission", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "putGroupUserPermission", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "user_id", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutPostGroupUserPermission" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUserPermission" } } } } } }, "delete": { "summary": "Delete User Group Permission", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "deleteGroupUserPermission", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "user_id", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NO CONTENT" } } } }, "/groups/{group_id}/request-access/": { "get": { "summary": "Current User Access Request", "description": "Fetches an existing access request to the group for the currently authenticated user.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getCurrentUserAccessRequest", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupAccessRequest" } } } }, "404": { "description": "NOT FOUND" } } }, "post": { "summary": "Request Access to Group", "description": "Submit an access request to the group for the currently authenticated user.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "postCurrentUserAccessRequest", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupAccessRequest" } } } }, "409": { "description": "CONFLICT - User already belongs to group" } } }, "delete": { "summary": "Revoke Access Request", "description": "Revokes the access request for the currently authenticated user.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "deleteCurrentUserAccessRequest", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NO CONTENT – The access request is deleted successfully." }, "404": { "description": "NOT FOUND" } } } }, "/groups/{group_id}/access-requests/": { "get": { "summary": "Get Access Request List", "description": "Fetches all outstanding access requests for the group.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getAccessRequestList", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "security", "in": "query", "description": "Filter by account security type.", "required": false, "schema": { "type": "string", "enum": [ "mfa", "remote_auth", "verified", "-mfa", "-remote_auth", "-verified" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "minimum": 0, "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupAccessRequest" }, { "type": "object", "properties": { "user": { "type": "object", "$ref": "#/components/schemas/RelatedUserSerializer" } } } ] } } } } }, "404": { "description": "NOT FOUND" } } } }, "/groups/{group_id}/access-requests/{request_id}": { "get": { "summary": "Get Access Request", "description": "Fetches an access requests for the group.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Groups" ], "operationId": "getAccessRequest", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "request_id", "in": "path", "required": true, "description": "The access request ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupAccessRequest" }, { "type": "object", "properties": { "user": { "type": "object", "$ref": "#/components/schemas/RelatedUserSerializer" } } } ] } } } }, "404": { "description": "NOT FOUND" } } }, "delete": { "summary": "Decline Access Request", "description": "Declines a users request to access the group. This will notify the requesting user that the request has been declined.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "declineAccessRequest", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "request_id", "in": "path", "required": true, "description": "The access request ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NOT CONTENT" } } } }, "/groups/{group_id}/access-requests/{request_id}/approve/": { "post": { "summary": "Approve Access Request", "description": "Approves a request to access the group. The user will be notified that the request has been approved.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Groups" ], "operationId": "approveGroupAccessRequest", "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The group ID", "schema": { "type": "integer" } }, { "name": "request_id", "in": "path", "required": true, "description": "The access request ID", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "CREATED" } } } }, "/users/": { "get": { "summary": "Get a list of users", "description": "Returns a list of all users in the site.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Users" ], "operationId": "getUserList", "parameters": [ { "name": "security", "in": "query", "description": "Filter by account security type.", "required": false, "schema": { "type": "string", "enum": [ "mfa", "remote_auth", "verified" ] } }, { "name": "group", "in": "query", "description": "Filter by group / site administrators", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "administrators" ] }, { "type": "integer", "description": "Filter by group ID" } ] } }, { "name": "seat_type", "in": "query", "description": "Filter by seat type", "required": false, "schema": { "type": "string", "enum": [ "paid", "none" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListSerializer" } } } } } } }, "/users/me/": { "get": { "summary": "Get the currently logged in user's details", "description": "Returns detail about the user who is currently authenticated with the API.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Users" ], "operationId": "getUserDetails", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoggedInUserSerializer" } } } } } } }, "/repos/": { "get": { "summary": "Returns a list of Repos you have access to.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getRepos", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoList" } } } } } }, "post": { "summary": "Create a new empty hosted Repository", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:write" ] } ], "tags": [ "Repositories" ], "operationId": "postRepo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCreateRequest" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoItemSerializer" } } } } } } }, "/repos/{org}/{slug}/": { "get": { "summary": "Fetch a single Repo", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getSingleRepo", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoItemSerializer" } } } } } }, "put": { "summary": "Update a repo", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:write" ] } ], "tags": [ "Repositories" ], "operationId": "updateSingleRepo", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoItemSerializer" } } } } } } }, "/repos/{org}/{slug}/clone-size-estimate/": { "get": { "summary": "Fetch an estimate for the on-disk size of Repo clone.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getRepoSize", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "query", "name": "depth", "schema": { "type": "integer" }, "example": 5, "description": "The depth, for a shallow clone, of objects to recieve, where the depths is the number of commits of history to include. by default includes all commits.\n" }, { "in": "query", "name": "spatial_filter", "schema": { "type": "string" }, "example": "POLYGON ((1752700 5921800, 1752700 5927200, 1757100 5927200, 1757100 5921800, 1752700 5921800))", "description": "Applies a spatial filter to the clone size estimate. The spatial-filter is a geometry encoded using either WKT or hex-encoded WKB. Kart-style spatial-filter specifications are also supported - where the CRS is prepended to the geometry and separated by a semicolon, eg \"EPSG:2193;\"\n" }, { "in": "query", "name": "spatial_filter_crs", "schema": { "type": "string" }, "example": "EPSG:2193", "description": "The CRS of the spatial-filter. Defaults to \"EPSG:4326\" if not specified here or prepended to spatial_filter." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCloneSizeSerializer" } } } } } } }, "/repos/{org}/{slug}/branches/": { "get": { "summary": "Fetch a list of branches available for this repo.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getAvailableBranches", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoBranchList" } } } } } } }, "/repos/{org}/{slug}/show/{commitish}": { "get": { "summary": "Fetch a specific commit", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getCommit", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "name": "commitish", "in": "path", "required": true, "description": "The commit or ref to show.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCommit" } } } } } } }, "/repos/{org}/{slug}/imports/": { "get": { "summary": "Fetch a list of imports for this repo.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:write" ] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "query", "name": "ref", "schema": { "type": "string" }, "example": "main", "description": "Branch or tag reference to filter imports by.\n" } ], "tags": [ "Repositories" ], "operationId": "getRepoImports", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoImportList" } } } } } }, "post": { "summary": "Create a new import for this repo.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:write" ] } ], "tags": [ "Repositories" ], "operationId": "postRepoImport", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoImportCreateRequest" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoImport" } } } } } } }, "/repos/{org}/{slug}/imports/{import_id}/": { "get": { "summary": "Fetch a specific import for this repo.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:write" ] } ], "tags": [ "Repositories" ], "operationId": "getRepoImportDetail", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "name": "import_id", "in": "path", "required": true, "description": "The ID of the import.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoImport" } } } } } } }, "/repos/{org}/{slug}/diff/{rev_range}/": { "get": { "summary": "Diff between two commits", "description": "Returns a diff in JSON or JSON-Lines format depending on the supplied Accept header.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getRepoDiff", "responses": { "200": { "description": "OK" } }, "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "path", "name": "rev_range", "schema": { "type": "string" }, "required": true, "description": "A Kart revision range. This is usually of the form \"X..Y\" or \"X...Y\", where X and Y are resolvable to commit IDs.\n", "example": "abcd1234...main" }, { "in": "query", "name": "crs", "description": "Reproject geometries into the given EPSG CRS.", "schema": { "type": "string", "example": "EPSG:2193", "pattern": "^EPSG:\\d+$" } } ] } }, "/repos/{org}/{slug}/log/{rev_range}/": { "get": { "summary": "Return a log for the given commit or revision range", "description": "Returns a diff in JSON or JSON-Lines format depending on the supplied Accept header.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getRepoLog", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "path", "name": "rev_range", "schema": { "type": "string" }, "required": true, "description": "A Kart revision range. This is either:\n* a single commit or ref\n* \"X..Y\" or \"X...Y\", where X and Y are resolvable to commit IDs.\n", "example": "abcd1234...main^" }, { "in": "query", "name": "with-change-counts", "schema": { "type": "boolean" }, "example": 1, "description": "Include a `featureChangeCounts` object in each commit: for each dataset that commit\nchanged, how many features it inserted, updated and deleted relative to its first\nparent, plus how many features that dataset contains at that commit.\nFor point cloud and raster datasets these refer to tiles rather than features.\n\nChange types with a count of zero are omitted, as are datasets that commit didn't\nchange at all, so a missing key means zero.\n\nThis is slower than a plain log, since the changes have to be counted for each\ncommit in the response.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoLog" } } } } } } }, "/repos/{org}/{slug}/tree/{commitish}/": { "get": { "summary": "List datasets in a repo", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "listRepoDatasets", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "path", "name": "commitish", "schema": { "type": "string" }, "required": true, "example": "main^" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoDatasetList" } } } } } } }, "/repos/{org}/{slug}/tree/{commitish}:{dataset_path}": { "get": { "summary": "Get a specific dataset", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getRepoDataset", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "path", "name": "commitish", "schema": { "type": "string" }, "required": true, "example": "main^" }, { "name": "dataset_path", "in": "path", "required": true, "description": "The path of the dataset within the repo.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoDatasetDetail" } } } } } } }, "/repos/{org}/{slug}/meta/{commitish}/": { "get": { "summary": "Get metadata about this repo", "description": "The response is given as a JSON object whose keys correspond to dataset paths.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "getRepoMeta", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "in": "path", "name": "commitish", "schema": { "type": "string" }, "required": true, "example": "main^" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoMeta" } } } } } } }, "/repos/{org}/{slug}/query-tiles/{ref}:{dataset_path}/": { "get": { "summary": "Returns a list of tiles in a point-cloud dataset", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "queryRepoTiles", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit reference.", "schema": { "type": "string" } }, { "name": "dataset_path", "in": "path", "required": true, "description": "The path of the point-cloud dataset within the repo.", "schema": { "type": "string" } }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": [ "name", "-name", "date_added", "-date_added", "date_updated", "-date_updated", "point_count", "-point_count", "point_density", "-point_density" ], "default": "name" }, "description": "Specifies a different sort order for the returned tiles. (By default they are sorted by name.) Prefixing your sort with `-` inverts the sort, so `-date_added` will return the newest tiles first.\n" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "example": "*auckland_AB34*", "description": "Limits the returned tiles to those whose names match the given search query string. May contain wildcards `*` (match any number of characters) and `?` (match any single character). Must match the entire tile name, including file extension. To match on a substring, put a `*` at the beginning and end of your query. All searches are case-insensitive.\n" }, { "in": "query", "name": "x", "schema": { "type": "number" }, "example": 79.3758, "description": "The x value of the point to query for. Must be used in conjunction with `y` and `crs`\n" }, { "in": "query", "name": "y", "schema": { "type": "number" }, "example": -35.2354, "description": "The y value of the point to query for in the requested CRS. Must be used in conjunction with `x` and `crs`\n" }, { "in": "query", "name": "radius", "schema": { "type": "number", "default": 1, "maximum": 10, "minimum": 0 }, "example": 5, "description": "The radius in **meters** to search for tiles in.\n" }, { "in": "query", "name": "crs", "schema": { "type": "string", "enum": [ "global", "native", "EPSG:XXXX" ] }, "description": "The CRS to use for the `x` and `y` parameters. Must be used in conjunction with `x` and `y`. If `global` is specified, the `x` and `y` parameters are assumed to be in EPSG:4326 (WGS84). If `native` is specified, the `x` and `y` parameters are assumed to be in the native CRS of the dataset. If an EPSG code is specified, the `x` and `y` parameters are assumed to be in that CRS.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoQueryTilesResponse" } } } } } } }, "/repos/{org}/{slug}/query-points/{ref}:{dataset_path}/": { "get": { "summary": "Returns a list of nearby points in a point-cloud dataset.", "description": "Returns a list of tiles near the query-point, and returns a list of points (found within those tiles) near the query point. All tiles that are within `radius` of the query point will be returned, unless further filters are specified, and they will be ordered using the specified sort-order. Only `num_points` points will be returned, ordered by their distance from the query point. This endpoint be thought of as an extension to the `query-tiles` endpoint: first the list of tiles is found, using the same logic as `query-tiles`, then a list of points is found from within those tiles.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "repos:read" ] } ], "tags": [ "Repositories" ], "operationId": "queryRepoPoints", "parameters": [ { "name": "org", "in": "path", "required": true, "description": "The namespace that owns the repo: an organisation slug, or the owning user's public_id for personally-owned repos.", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "The slug identifying the repo within the organisation.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit reference.", "schema": { "type": "string" } }, { "name": "dataset_path", "in": "path", "required": true, "description": "The path of the point-cloud dataset within the repo.", "schema": { "type": "string" } }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": [ "name", "-name", "date_added", "-date_added", "date_updated", "-date_updated", "point_count", "-point_count", "point_density", "-point_density" ], "default": "name" }, "description": "Specifies a different sort order for the returned tiles. (By default they are sorted by name.) Prefixing your sort with `-` inverts the sort, so `-date_added` will return the newest tiles first.\n" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "example": "*auckland_AB34*", "description": "Limits the returned tiles to those whose names match the given search query string. May contain wildcards `*` (match any number of characters) and `?` (match any single character). Must match the entire tile name, including file extension. To match on a substring, put a `*` at the beginning and end of your query. All searches are case-insensitive. Filtering returned tiles indirectly filters returned points, since all returned points will be found somewhere within the returned tiles.\n" }, { "in": "query", "name": "x", "schema": { "type": "number" }, "example": 79.3758, "description": "The x value of the point to query for. Required.\n" }, { "in": "query", "name": "y", "schema": { "type": "number" }, "example": -35.2354, "description": "The y value of the point to query for in the requested CRS. Required.\n" }, { "in": "query", "name": "radius", "schema": { "type": "number", "default": 1, "maximum": 10, "minimum": 0 }, "example": 5, "description": "The radius in **meters** to search for tiles in.\n" }, { "in": "query", "name": "crs", "schema": { "type": "string", "enum": [ "global", "native", "EPSG:XXXX" ] }, "description": "The CRS to use for the `x` and `y` parameters. Required. If `global` is specified, the `x` and `y` parameters are assumed to be in EPSG:4326 (WGS84). If `native` is specified, the `x` and `y` parameters are assumed to be in the native CRS of the dataset. If an EPSG code is specified, the `x` and `y` parameters are assumed to be in that CRS.\n" }, { "in": "query", "name": "num_points", "schema": { "type": "integer", "default": 10, "maximum": 1000, "minimum": 1 }, "description": "The number of points to return, starting with the point to the query-point. All returned points will be found within the returned tiles, but it may be that some of the returned tiles don't provide any points which are among the closest `num_points` points.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoQueryPointsResponse" } } } } } } }, "/exports/": { "post": { "summary": "Create a new export", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "exports:write" ] } ], "tags": [ "Exports" ], "operationId": "postExport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreateRequest" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportItemSerializer" } } } } } }, "get": { "summary": "List exports", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "exports:read" ] } ], "tags": [ "Exports" ], "operationId": "getExports", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportList" } } } } } }, "options": { "summary": "Get export options", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "exports:read" ] } ], "tags": [ "Exports" ], "operationId": "getExportOptions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportOptionsResponse" } } } } } } }, "/exports/validate/": { "post": { "summary": "Validate export", "description": "The Export Validation endpoint accepts the same content as the Export Creation API but will not create/start the export and will return additional information.\n### Error Codes\nThe following errors are returned as part of a `400` response when the validation request itself fails. The paths below indicate where the error will be found in the nested respone, for example:\n```json\n {\n \"error_code\": 400,\n \"errors\": {\n \"items\": [\n `no-items: You must request at least one item`\n ]\n }\n }\n```\n* `errors`\n * `items`\n * `no-items: You must request at least one item` \\\n * `duplicate-items: Duplicate items were requested`\n * [`index`]\n * `item`\n * `Invalid hyperlink - No URL match.`\n * `crs`\n * `Invalid CRS`\n * `Unknown CRS`\n* `formats`\n * `No format was selected for layers of type '{kind}'`\n\nThe following error codes are returned as part of a `200` response which will include other information about the Export validation.\n* `invalid_reasons`\n * `kml-invalid-crs`\n * `missing-crs`\n * `no-layers`\n * `over-size-limit:max-{overall-size-limit}`\n * `under-sized-courier-export:min-{overall-size-limit}`\n * `over-size-limit:{mime-type}:max-{format-size-limit}`\n * `missing-shipping_address-field:{field_name}`\n\n* `items`\n * [`index`]\n * `invalid_reasons`\n * `commercial-data-not-supported`\n * `outside-extent`\n * `online-only`\n * `invalid-for-given-crs`\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "exports:write" ] } ], "tags": [ "Exports" ], "operationId": "validateExportRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportItemValidationResult" } } } }, "400": { "description": "Validation Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/exports/croplayers/": { "get": { "summary": "List crop layers", "description": "Crop layers make a vector layer's polygons available as named extents to crop exports with. Source features with non-blank labels become *crop features*. For example, a district's crop feature limits an export to data inside that district.\n\nOnly active crop layers are listed. A crop layer that is still importing its features, or whose import failed, does not appear here and cannot be used until the import finishes.\n\nA crop layer's `name` is the title of the source layer's published version, and its `extent` is that layer's extent — neither is settable on the crop layer. To rename a crop layer, rename the source layer.\n\nAPI tokens need the `exports:read` scope.\n", "tags": [ "Exports" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getCropLayers", "parameters": [ { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "features" ] }, "description": "Inlines each crop layer's crop features instead of linking to them. May include obsolete features after regeneration; follow the `features` URL for current features.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropLayerList" } } } } } }, "post": { "summary": "Create a crop layer", "description": "Turns a published vector layer into a crop layer. The authenticated user must be a site administrator, and the site's plan must include crop layers. No particular API token scope is required.\n\nThe source layer must be published, vector, polygon, and have at most 1000 features. Its `label_attribute` field supplies each crop feature's name, and must be a string field of the layer. Labels are trimmed; features with null or blank labels are skipped. Import fails if no usable labels remain.\n\nCreating a crop layer for a layer that already has one **replaces** it: the old crop layer is deleted, and its crop feature URLs stop working. Publishing changed source data automatically queues crop feature regeneration; another POST is unnecessary.\n\nReturns `{}` and imports features asynchronously. Poll `/exports/croplayers/` with a timeout until the crop layer appears. These endpoints cannot distinguish pending imports from failed imports.\n", "tags": [ "Exports" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "createCropLayer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropLayerCreateRequest" } } } }, "responses": { "201": { "description": "Created. The body is an empty object — the crop layer is still importing its features.\n", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation failed: the layer is unpublished, not a polygon vector layer, has more than 1000 features, `label_attribute` is not a string field of the layer, or the site's plan does not include crop layers.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "The authenticated user is not a site administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/exports/croplayers/{croplayer_id}/": { "parameters": [ { "name": "croplayer_id", "in": "path", "required": true, "description": "The crop layer ID.", "schema": { "type": "integer" } } ], "get": { "summary": "Get a crop layer", "description": "A crop layer that isn't active is a 404 here. API tokens need the `exports:read` scope.\n", "tags": [ "Exports" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getCropLayer", "parameters": [ { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "features" ] }, "description": "Inlines crop features, including obsolete features after regeneration. Follow the `features` URL for current features.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropLayer" } } } } } }, "delete": { "summary": "Delete a crop layer", "description": "Requires a site administrator; no particular API token scope is required. The crop layer and its crop features stop being usable immediately; the source layer itself is untouched. Exports already created with one of its crop features keep their extent.\n", "tags": [ "Exports" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "deleteCropLayer", "responses": { "204": { "description": "No Content" }, "403": { "description": "The authenticated user is not a site administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/exports/croplayers/{croplayer_id}/cropfeatures/": { "parameters": [ { "name": "croplayer_id", "in": "path", "required": true, "description": "The crop layer ID.", "schema": { "type": "integer" } } ], "get": { "summary": "List crop features", "description": "The crop features of a crop layer, ordered by name. Pass a crop feature's `url` as an export's `extent` to crop that export to it.\n\nThis list is paginated. Use `?page_size=1000` to request the maximum page size. Geometries are omitted here; fetch a crop feature individually to get its geometry.\n\nAPI tokens need the `exports:read` scope.\n", "tags": [ "Exports" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getCropFeatures", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropFeatureList" } } } } } } }, "/exports/croplayers/{croplayer_id}/cropfeatures/{cropfeature_id}/": { "parameters": [ { "name": "croplayer_id", "in": "path", "required": true, "description": "The crop layer ID, or the literal string `upload` for a crop feature that a user uploaded rather than one that came from a crop layer.\n", "schema": { "type": "string", "example": "12" } }, { "name": "cropfeature_id", "in": "path", "required": true, "description": "The crop feature ID.", "schema": { "type": "integer" } } ], "get": { "summary": "Get a crop feature", "description": "Returns simplified geometry. Exports use the full geometry. API tokens need the `exports:read` scope.\n", "tags": [ "Exports" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getCropFeature", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropFeatureDetail" } } } } } } }, "/notifications/sse/": { "get": { "summary": "Subscribe to notifications (server-sent events)", "description": "Streams notifications about the authenticated user's own asynchronous\njobs as they finish, so clients don't have to poll `/publish/{id}/` or\n`/sources/{id}/scans/{scan}/`.\n\nThe response is a `text/event-stream` (see\n[Server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)).\nIt starts with `retry: 2000`, asking the client to reconnect after 2\nseconds if the connection drops, and then carries two kinds of event:\n\n * `event: notify` — a notification. The `data` line is one JSON\n object; see the `Notification` schema below.\n * `event: ping` — a keep-alive with empty `data`, sent after 30\n seconds without a notification. Ignore it.\n\nDelivery semantics:\n\n * Notifications are only delivered to connections that are open at\n the moment the job finishes; nothing is queued or replayed. After\n connecting (or reconnecting) re-fetch the status of any job you are\n waiting on, in case it finished in between.\n * Notifications are scoped to the site the job ran on: connect to\n this endpoint on the same domain you started the job on.\n * Only the user who started the job is notified.\n\nNotifications are grouped into channels. Each notification carries its\n`channel`, an `event` name, and event-specific `data`:\n\n| Channel | Event | `data` |\n|--------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `publishing` | `publish-finished` | `id`, `state` (`completed`, `errored`, `cancelled` or `cancelled-due-to-error`), `url` (the publish's API URL) |\n| `scans` | `scan-finished` | `id`, `status` (`completed`, `error` or `cancelled`), `url` (the scan's API URL), `source` (the source's API URL). Only scans started via the API notify; scheduled scans have no user to tell. |\n| `exports` | `export-completed` | `id`, `size` (bytes, zipped), `url` (site download page) |\n| `exports` | `export-failed` | `id`, and `ticket_url` when a support ticket was raised |\n| `exports` | `export-cancelled` | `id` |\n| `exports` | `export-progress` | Periodic progress of running exports |\n| `mapviewers` | `key-updated`, `created`, `deleted`, `parent-deleted` | Internal: changes to the user's map viewers |\n\nFor example, once a publish completes:\n\n```\nevent: notify\ndata: {\"channel\": \"publishing\", \"event\": \"publish-finished\", \"data\": {\"id\": 42, \"state\": \"completed\", \"url\": \"https://{domain}/services/api/v1.x/publish/42/\"}}\n```\n\nClients that can't hold an event-stream open can use the long-poll\nvariant at `/notifications/poll/` instead.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Notifications" ], "operationId": "subscribeNotificationsSse", "responses": { "200": { "description": "OK. An event stream that stays open until the client disconnects.", "content": { "text/event-stream": { "schema": { "type": "string", "example": "retry: 2000\n\nevent: ping\ndata:\n\nevent: notify\ndata: {\"channel\": \"scans\", \"event\": \"scan-finished\", \"data\": {\"id\": 7, \"status\": \"completed\", \"url\": \"https://{domain}/services/api/v1.x/sources/3/scans/7/\", \"source\": \"https://{domain}/services/api/v1.x/sources/3/\"}}\n" } } } }, "401": { "description": "Not authenticated" }, "403": { "description": "The token doesn't have the `notifications:read` scope" } } } }, "/notifications/poll/": { "get": { "summary": "Wait for a notification (long poll)", "description": "Long-polling alternative to `/notifications/sse/`, for clients that\ncan't consume an event stream. Delivers the same notifications with\nthe same semantics (see the SSE endpoint for the channels and their\npayloads).\n\nThe request is held open until a notification for the user arrives, or\nfor 80 seconds, whichever comes first:\n\n * On a notification, the body is that one notification as a JSON\n object (the `Notification` schema) and the request ends. Re-request\n immediately to wait for the next one.\n * On timeout the body is empty. Re-request immediately.\n\nOnly one notification is returned per request, and anything that\nhappens while no request is in flight is lost, so re-fetch the status\nof jobs you are waiting on when you start polling.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Notifications" ], "operationId": "pollNotifications", "responses": { "200": { "description": "OK. One notification, or an empty body if none arrived within 80 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "401": { "description": "Not authenticated" }, "403": { "description": "The token doesn't have the `notifications:read` scope" } } } }, "/site/": { "get": { "summary": "Returns details for the current site (warehouse)", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "getSite", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSerializer" } } } } } } }, "/site/access-requests/": { "get": { "summary": "Returns a list of access requests for the current site.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "getRequests", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAccessRequestList" } } } } } }, "post": { "summary": "Create a new site access request", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "postRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAccessRequestCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAccessRequest" } } } } } } }, "/site/menu/": { "get": { "summary": "Get custom user menus", "security": [ { "SessionAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "getUserMenus", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMenuListAndCreateResponse" } } } } } }, "put": { "summary": "Update custom user menus", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "updateUserMenus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMenuCreateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMenuListAndCreateResponse" } } } } } } }, "/site/help-menu/": { "get": { "summary": "Get custom help menu URLs", "security": [ { "SessionAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "getHelpMenus", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpMenuListAndCreateResponse" } } } } } }, "put": { "summary": "Update custom help menu URLs", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Sites" ], "operationId": "updateHelpMenus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpMenuCreateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpMenuListAndCreateResponse" } } } } } } }, "/site/external-service-templates/": { "get": { "summary": "List external service templates", "description": "Lists the external service templates defined for the site. Requires\ndata administration rights, and the external services feature must be\nenabled on the site.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Services" ], "operationId": "getExternalServiceTemplates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceTemplateList" } } } }, "403": { "description": "You lack data administration rights." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } }, "post": { "summary": "Create external service template", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Services" ], "operationId": "postExternalServiceTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceTemplateWriteRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceTemplate" } } } }, "403": { "description": "You are not a site administrator." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } } }, "/site/external-service-templates/{template_id}/": { "get": { "summary": "Get external service template", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Services" ], "operationId": "getExternalServiceTemplate", "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The external service template ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceTemplate" } } } }, "403": { "description": "You lack data administration rights." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } }, "put": { "summary": "Update external service template", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Services" ], "operationId": "putExternalServiceTemplate", "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The external service template ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceTemplateWriteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceTemplate" } } } }, "403": { "description": "You are not a site administrator." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } }, "delete": { "summary": "Delete external service template", "description": "Deletes the template. All external services previously created from\nthis template are also deleted (their `deleted_at` is set).\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Services" ], "operationId": "deleteExternalServiceTemplate", "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The external service template ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "You are not a site administrator." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } } }, "/layers/{layer_id}/pin/": { "post": { "summary": "Pin dataset", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Pinning" ], "operationId": "postDataset", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "OK" } } }, "delete": { "summary": "Un-pin dataset", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Pinning" ], "operationId": "deleteDataset", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "OK" } } } }, "/layers/{layer_id}/services/": { "get": { "summary": "List Services", "description": "Lists the data services configured for the owning layer, table, set or catalog item.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Services" ], "operationId": "getServices", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicesList" } } } } } } }, "/layers/{layer_id}/services/{service_id}/": { "get": { "summary": "Get Service Detail", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Services" ], "operationId": "getServiceDetail", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } } } }, "put": { "summary": "Update Service Availability", "description": "Enable or disable the service for its owner. Cannot disable ad-hoc services or service types that do not enforce permissions.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "putService", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUpdateRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/layers/{layer_id}/services/{service_id}/permissions/": { "get": { "summary": "List Service Permissions", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Services" ], "operationId": "getServicePermissions", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicePermissionList" } } } } } }, "post": { "summary": "Create Service Permission", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "postServicePermissions", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicePermissionCreateRequest" } } } }, "responses": { "201": { "description": "CREATED" } } }, "put": { "summary": "Replace Service Permissions", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "putServicePermission", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicePermissionListReplaceRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/layers/{layer_id}/services/{service_id}/permissions/{owner_key}/": { "get": { "summary": "Get Service Permission", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Services" ], "operationId": "getServicePermission", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } }, { "name": "owner_key", "in": "path", "required": true, "description": "The owner key, e.g. `user.123` or `group.45`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicePermission" } } } } } }, "delete": { "summary": "Delete Service Permission", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "deleteServicePermission", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } }, { "name": "owner_key", "in": "path", "required": true, "description": "The owner key, e.g. `user.123` or `group.45`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/layers/{layer_id}/external-services/": { "post": { "summary": "Attach external service", "description": "Attaches an external service to the layer or table from an external\nservice template. The template's `service_url` tokens are resolved using\nthe dataset, and the resulting service is returned.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "postExternalService", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer or table ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceAttachRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } }, "403": { "description": "You are not a site administrator, or lack admin permission on the dataset." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } } }, "/layers/{layer_id}/external-services/{service_id}/": { "get": { "summary": "Get external service detail", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "tags": [ "Services" ], "operationId": "getExternalService", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer or table ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } }, "403": { "description": "You are not a site administrator, or lack admin permission on the dataset." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } }, "put": { "summary": "Update external service", "description": "Enable or disable the external service for its owner.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "putExternalService", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer or table ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceUpdateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } }, "403": { "description": "You are not a site administrator, or lack admin permission on the dataset." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } }, "delete": { "summary": "Delete external service", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "tags": [ "Services" ], "operationId": "deleteExternalService", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer or table ID", "schema": { "type": "integer" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "You are not a site administrator, or lack admin permission on the dataset." }, "404": { "description": "Not found, or the external services feature is not enabled on the site." } } } }, "/categories/": { "get": { "summary": "Get categories", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Categories" ], "operationId": "getCategories", "responses": { "200": { "description": "Recursive list of nested categories. See example below :\n```\n[\n {\n \"name\": \"category 1\",\n \"slug\": \"category-1\",\n \"key\": \"category-1\",\n \"url\": \"https://testserver.com/services/api/v1.x/categories/category-1/\",\n \"children\": [\n {\n \"name\": \"category 2\",\n \"slug\": \"category-2\",\n \"key\": \"category-1/category-2\",\n \"url\": \"https://testserver.com/services/api/v1.x/categories/category-1/category-2/\",\n \"children\": [\n {\n \"name\": \"category 3\",\n \"slug\": \"category-3\",\n \"key\": \"category-1/category-2/category-3\",\n \"url\": \"https://testerver.com/services/api/v1.x/categories/category-1/category-2/category-3/\",\n \"children\": []\n }\n ]\n }\n ]\n },\n {\n \"name\": \"category 4\",\n \"slug\": \"category-4\",\n \"key\": \"category-4\",\n \"url\": \"https://testserver.com/services/api/v1.x/categories/category-4/\",\n \"children\": []\n }\n]\n```\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } } } }, "post": { "summary": "Create a new category", "description": "Requires site administrator privileges.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Categories" ], "operationId": "postCategory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCategoryRequest" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCategoryResponse" } } } } } } }, "/categories/{category_url}/": { "get": { "summary": "Fetch a single category", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Categories" ], "operationId": "getSingleCategory", "parameters": [ { "name": "category_url", "in": "path", "required": true, "description": "The slash-separated key/slug path of the category (e.g. \"parent-slug/child-slug\"). Slashes are literal path separators — pass the path as-is; do not URL-encode them.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryItemSerializer" } } } } } }, "post": { "summary": "Create a child category", "description": "Create a new category nested under the addressed category. Requires site administrator privileges.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Categories" ], "operationId": "postChildCategory", "parameters": [ { "name": "category_url", "in": "path", "required": true, "description": "The slash-separated key/slug path of the parent category (e.g. \"parent-slug/child-slug\"). Slashes are literal path separators — pass the path as-is; do not URL-encode them.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCategoryRequest" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCategoryResponse" } } } } } }, "put": { "summary": "Update a category", "description": "Requires site administrator privileges.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Categories" ], "operationId": "updateCategory", "parameters": [ { "name": "category_url", "in": "path", "required": true, "description": "The slash-separated key/slug path of the category (e.g. \"parent-slug/child-slug\"). Slashes are literal path separators — pass the path as-is; do not URL-encode them.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCategoryRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryItemSerializer" } } } } } }, "delete": { "summary": "Delete a category", "description": "Cascade-deletes the category and its descendants. Requires site administrator privileges.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Categories" ], "operationId": "deleteCategory", "parameters": [ { "name": "category_url", "in": "path", "required": true, "description": "The slash-separated key/slug path of the category (e.g. \"parent-slug/child-slug\"). Slashes are literal path separators — pass the path as-is; do not URL-encode them.\n", "schema": { "type": "string" } } ], "responses": { "204": { "description": "NO CONTENT" } } } }, "/tokens/": { "get": { "summary": "List API Tokens", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "getTokens", "parameters": [ { "in": "query", "name": "include_expired", "description": "Include tokens whose ```expires_at``` is in the past.\nDefaults to ```false```: expired tokens are omitted from the list unless you explicitly ask for them.\nExpiry is not permanent. The detail endpoint (```/tokens/{token_id}/```) returns an expired token regardless of this parameter, and ```PUT```ting a new future ```expires_at``` to it makes the token usable again.\n", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenList" } } } } } }, "post": { "summary": "Create an API Token", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "postToken", "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedTokenWithKey" } } } } } } }, "/tokens/{token_id}/": { "get": { "summary": "Get API Token", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "getTokenById", "parameters": [ { "name": "token_id", "in": "path", "required": true, "description": "The ID of the API token.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedToken" } } } } } }, "put": { "summary": "Update an API Token", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "updateToken", "parameters": [ { "name": "token_id", "in": "path", "required": true, "description": "The ID of the API token.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedToken" } } } } } }, "delete": { "summary": "Delete an API Tokens", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "deleteToken", "parameters": [ { "name": "token_id", "in": "path", "required": true, "description": "The ID of the API token.", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NO CONTENT" } } } }, "/tokens/{token_id}/suspend/": { "post": { "summary": "Suspend an API Token", "description": "Stop a token authenticating, reversibly. Unlike deleting a token this can be undone — see the resume endpoint. A suspended token still appears in the token list, and the response is the full token detail with ```suspended_at``` set.\n```suspended_at``` is server-controlled: it cannot be set or cleared by ```PUT```ting the detail endpoint.\n", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "suspendToken", "parameters": [ { "name": "token_id", "in": "path", "required": true, "description": "The ID of the API token.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedToken" } } } } } } }, "/tokens/{token_id}/resume/": { "post": { "summary": "Resume a suspended API Token", "description": "Undo a suspension, clearing ```suspended_at``` and letting the token authenticate again. Resuming a token that isn't suspended is a no-op.\n", "security": [ { "SessionAuthentication": [] }, { "BearerAuthToken": [] } ], "tags": [ "API Tokens" ], "operationId": "resumeToken", "parameters": [ { "name": "token_id", "in": "path", "required": true, "description": "The ID of the API token.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedToken" } } } } } } }, "/data/": { "get": { "summary": "Search the catalog", "description": "Lists every published item visible to you - layers, tables, sets, documents, Kart repositories and datasets, map viewers and catalog items - in one result set. Each result carries a `type` field. The `/layers/`, `/tables/`, `/items/` and `/sources/` lists are this search narrowed to one type, and accept the same filters.\n\nQuery parameters not listed here are ignored, not rejected.\n", "tags": [ "Data Catalog" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getData", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataList" } } } } } } }, "/data/drafts/": { "get": { "summary": "Search draft items", "description": "As for `/data/`, but returns the unpublished draft version of each item, and only items you can administer. Items whose latest version is already published do not appear.\n", "tags": [ "Data Catalog" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDataDrafts", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" }, { "$ref": "#/components/parameters/SearchVersionStatusParameter" }, { "$ref": "#/components/parameters/SearchHasDraftParameter" }, { "$ref": "#/components/parameters/SearchActivityParameter" }, { "$ref": "#/components/parameters/SearchErroredParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataList" } } } } } } }, "/data/latest/": { "get": { "summary": "Search items, showing latest versions", "description": "As for `/data/`, but returns the latest version of each item: the draft version for items you can administer, otherwise the published version.\n", "tags": [ "Data Catalog" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDataLatest", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" }, { "$ref": "#/components/parameters/SearchVersionStatusParameter" }, { "$ref": "#/components/parameters/SearchHasDraftParameter" }, { "$ref": "#/components/parameters/SearchActivityParameter" }, { "$ref": "#/components/parameters/SearchErroredParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataList" } } } } } } }, "/layers/": { "get": { "summary": "List layers and tables", "description": "List layers (at `layers/`) and tables (at `tables/`) respectively. This is the `/data/` search narrowed to one type, and accepts the same filters. Query parameters not listed here are ignored, not rejected.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Layers" ], "operationId": "getLayersTables", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/SearchSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTables" } } } } } }, "post": { "summary": "Post layers or tables", "description": "All fields except ```name``` and ```data.datasources``` are optional.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Layers" ], "operationId": "postLayersTables", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesPostRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerDetail" } } } } } } }, "/layers/drafts/": { "get": { "summary": "Get a filterable list view of layers", "description": "A filterable list views of layers (```layers/drafts/```) and and tables (```tables/drafts/```) respectively, similar to ```/layers/``` and ```/tables/```. This view shows the draft version of each layer or table. If the most recent version of a layer or table has been published already, it will not appear here.\n\n All the same filters and ordering from ```layers/``` and ```tables/``` apply.", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "tags": [ "Layers" ], "operationId": "getFilteredLayersTables", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" }, { "$ref": "#/components/parameters/SearchVersionStatusParameter" }, { "$ref": "#/components/parameters/SearchHasDraftParameter" }, { "$ref": "#/components/parameters/SearchActivityParameter" }, { "$ref": "#/components/parameters/SearchErroredParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesDraft" } } } } } } }, "/layers/latest/": { "get": { "summary": "List layers or tables, showing latest versions", "description": "As for `layers/` and `tables/`, but returns the latest version of each layer or table: the draft version for those you can administer, otherwise the published version. All the same filters and ordering apply.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Layers" ], "operationId": "getLatestLayersTables", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" }, { "$ref": "#/components/parameters/SearchVersionStatusParameter" }, { "$ref": "#/components/parameters/SearchHasDraftParameter" }, { "$ref": "#/components/parameters/SearchActivityParameter" }, { "$ref": "#/components/parameters/SearchErroredParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesDraft" } } } } } } }, "/tables/": { "get": { "summary": "List tables", "description": "As for `/layers/`, narrowed to tables. `POST /tables/` behaves as `POST /layers/`.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Layers" ], "operationId": "getTables", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/SearchSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTables" } } } } } } }, "/tables/drafts/": { "get": { "summary": "List draft tables", "description": "As for `/layers/drafts/`, narrowed to tables.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Layers" ], "operationId": "getTablesDrafts", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" }, { "$ref": "#/components/parameters/SearchVersionStatusParameter" }, { "$ref": "#/components/parameters/SearchHasDraftParameter" }, { "$ref": "#/components/parameters/SearchActivityParameter" }, { "$ref": "#/components/parameters/SearchErroredParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesDraft" } } } } } } }, "/tables/latest/": { "get": { "summary": "List tables, showing latest versions", "description": "As for `/layers/latest/`, narrowed to tables.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Layers" ], "operationId": "getLatestTables", "parameters": [ { "$ref": "#/components/parameters/SearchQParameter" }, { "$ref": "#/components/parameters/DataSortParameter" }, { "$ref": "#/components/parameters/SearchFacetsParameter" }, { "$ref": "#/components/parameters/SearchIdParameter" }, { "$ref": "#/components/parameters/SearchKindParameter" }, { "$ref": "#/components/parameters/SearchGeometryTypeParameter" }, { "$ref": "#/components/parameters/SearchStorageParameter" }, { "$ref": "#/components/parameters/SearchPublicParameter" }, { "$ref": "#/components/parameters/SearchIsStarredParameter" }, { "$ref": "#/components/parameters/SearchIsPinnedParameter" }, { "$ref": "#/components/parameters/SearchHasRepoParameter" }, { "$ref": "#/components/parameters/SearchPublishingParameter" }, { "$ref": "#/components/parameters/SearchPublishErroredParameter" }, { "$ref": "#/components/parameters/SearchAutoupdateParameter" }, { "$ref": "#/components/parameters/SearchFirstImportParameter" }, { "$ref": "#/components/parameters/SearchCropLayerEligibleParameter" }, { "$ref": "#/components/parameters/SearchUpdatableParameter" }, { "$ref": "#/components/parameters/SearchIsFeaturedParameter" }, { "$ref": "#/components/parameters/SearchHasZParameter" }, { "$ref": "#/components/parameters/SearchIsImageryParameter" }, { "$ref": "#/components/parameters/SearchHasPkParameter" }, { "$ref": "#/components/parameters/SearchRasterBandParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionLtParameter" }, { "$ref": "#/components/parameters/SearchRasterResolutionGtParameter" }, { "$ref": "#/components/parameters/SearchCreatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchCreatedAfterParameter" }, { "$ref": "#/components/parameters/SearchUpdatedBeforeParameter" }, { "$ref": "#/components/parameters/SearchUpdatedAfterParameter" }, { "$ref": "#/components/parameters/SearchFeaturedBeforeParameter" }, { "$ref": "#/components/parameters/SearchFeaturedAfterParameter" }, { "$ref": "#/components/parameters/SearchPtParameter" }, { "$ref": "#/components/parameters/SearchDistanceParameter" }, { "$ref": "#/components/parameters/SearchGeometryParameter" }, { "$ref": "#/components/parameters/SearchServiceParameter" }, { "$ref": "#/components/parameters/SearchLicenseParameter" }, { "$ref": "#/components/parameters/SearchLicenseTypeParameter" }, { "$ref": "#/components/parameters/SearchLicenseJurisdictionParameter" }, { "$ref": "#/components/parameters/SearchLicenseVersionParameter" }, { "$ref": "#/components/parameters/SearchCategoryParameter" }, { "$ref": "#/components/parameters/SearchGeotagParameter" }, { "$ref": "#/components/parameters/SearchTagParameter" }, { "$ref": "#/components/parameters/SearchGroupParameter" }, { "$ref": "#/components/parameters/SearchAccessGroupParameter" }, { "$ref": "#/components/parameters/SearchOrgParameter" }, { "$ref": "#/components/parameters/SearchUserParameter" }, { "$ref": "#/components/parameters/SearchFromParameter" }, { "$ref": "#/components/parameters/SearchContextParameter" }, { "$ref": "#/components/parameters/SearchRoleParameter" }, { "$ref": "#/components/parameters/SearchVersionStatusParameter" }, { "$ref": "#/components/parameters/SearchHasDraftParameter" }, { "$ref": "#/components/parameters/SearchActivityParameter" }, { "$ref": "#/components/parameters/SearchErroredParameter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesDraft" } } } } } } }, "/layers/{layer_id}/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } } ], "get": { "summary": "Get details of a layer or a table", "description": "Displays details of a layer ```layers/{id}/``` or a table ```tables/{id}/```. This view displays the published version only. To get the latest version, hit ```/layers/{id}/versions/latest/```\n\n Both of these URLs work for either layers or tables. This is because layers can be turned into tables and vice versa. If ```/tables/123/``` is hit for a layer, or ```/layers/123/``` for a table, the behaviour and response will be the same as the “correct” URL, except that the response will contain a Location header specifying the canonical URL. This applies to all sub-urls also (```permissions/```, ```metadata/```, ```versions/```, etc)", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "operationId": "getLayersById", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerDetail" } } } } } }, "put": { "summary": "Change the owner of a layer or table", "description": "Change the owner (user or group) of a layer or table. Ownership takes\neffect immediately and is not tied to publishing a new version.\n", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "operationId": "changeLayerOwner", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerOwnerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerDetail" } } } } } }, "delete": { "summary": "Delete a layer", "description": "Deletes specified layer.", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "operationId": "deleteLayerById", "responses": { "204": { "description": "OK" } } } }, "/layers/{layer_id}/versions/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } } ], "get": { "summary": "Filterable view of a specific layer or table versions", "description": "Filterable list views of versions of a specific layer or table, always sorted newest to oldest.\n\n Parameters\n data__source_revision: number (optional). If the version s source supports revisions, find versions using a specific revision. Values depend on the source type. Optionally use data__source_revision__lt ordata__source_revision__gte to filter using < or >= operators respectively.", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "operationId": "getLayersVersion", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesVersionList" } } } } } }, "post": { "summary": "Create a new draft version", "description": "Creates a new draft version, accepting the same content as ```POST layers/```. If anything in the ```data``` object has changed then an import will begin immediately. Otherwise to force a re-import from the previous sources call ```layers/{id}/versions/{version}/import/```.", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "operationId": "postLayersVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayersTablesPostDraft" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "ERROR", "content": { "application/json": { "schema": { "type": "string", "example": { "error": "There is already a draft version active for this layer." } } } } } } } }, "/layers/{layer_id}/versions/{version_id}/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "ID of the version", "schema": { "type": "string" } } ], "get": { "summary": "Fetch a specific layer version", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:read" ] } ], "operationId": "getLayerVersion", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerDetail" } } } } } } }, "/layers/{layer_id}/versions/{version_id}/datasources/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "ID of the version", "schema": { "type": "string" } } ], "get": { "tags": [ "Layers" ], "summary": "Get datasources used to import this layer", "operationId": "getLayerVersionDatasources", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DatasourceDetail" } } } } } } } }, "/layers/{layer_id}/versions/{version_id}/datasources/urls/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "ID of the version", "schema": { "type": "string" } } ], "get": { "tags": [ "Layers" ], "summary": "Get datasources used to import this layer (URLs only)\n", "operationId": "getLayerVersionDatasourcesUrlsOnly", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DatasourceUrlOnly" } } } } } } } }, "/layers/{layer_id}/versions/{version_id}/tiles/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "ID of the version", "schema": { "type": "integer" } } ], "get": { "tags": [ "Layers" ], "summary": "List the raster tiles of a layer version", "description": "Lists the raster tiles imported for a raster layer version. Only\navailable for raster layers (raster, RAT and grid); other layer types\nreturn ```404```. Requires ```admin``` permission on the layer.\n\nUse the ```status``` filter to select which tiles to list:\n\n - ```current``` (default) — tiles that are live in this version.\n - ```unused``` — tiles from earlier revisions that have been replaced\n and are no longer referenced, but whose data has not been deleted.\n These are the tiles that ```tiles/delete/``` can reclaim.\n - ```deleted``` — tiles whose space has been reclaimed (their storage\n has been, or is being, deleted from object storage). Deleted tiles\n are not billed against the layer's storage usage.\n\nThe ```summary``` reports the total ```count``` and combined ```size```\n(in bytes) of all tiles matching the filter, across all pages. Sizes\nare measured the way the layer's storage is billed, not as the\ncompressed size in object storage, so they match the layer's storage\nusage reports.\n", "operationId": "getLayerVersionTiles", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "parameters": [ { "in": "query", "name": "status", "description": "Which set of tiles to list.", "schema": { "type": "string", "enum": [ "current", "unused", "deleted" ], "default": "current" } }, { "in": "query", "name": "page", "description": "Page number to return.", "schema": { "type": "integer" } }, { "in": "query", "name": "page_size", "description": "Number of tiles per page (maximum ```100000```). If omitted, the entire result set is returned in one unpaginated response (with no pagination headers).\n", "schema": { "type": "integer", "maximum": 100000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerVersionTilesList" } } } }, "400": { "description": "Invalid ```status``` value." }, "404": { "description": "Layer or version not found, the user lacks ```admin``` permission, or the layer version is not a raster layer.\n" } } } }, "/layers/{layer_id}/versions/{version_id}/tiles/delete/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "ID of the version", "schema": { "type": "integer" } } ], "post": { "tags": [ "Layers" ], "summary": "Delete unused raster tiles to reclaim storage", "description": "Marks unused raster tiles of a published layer version for deletion and\nreclaims their object storage. Only ```unused``` tiles (see\n```tiles/```) are affected; tiles that are still current are ignored.\n\nRequires ```admin``` permission on the layer. Only published versions\nare supported — deleting tiles of a draft version returns ```400```.\n\nThe marked tiles are removed from the layer's billable size\nimmediately, then their storage objects are deleted asynchronously; the\ntiles move to the ```deleted``` status straight away.\n\nProvide either ```tile_ids``` (a list of tile ids from ```tiles/```) or\n```all: true``` to reclaim every unused tile of the version. If both are\ngiven, ```all``` selects the tiles, but ```tile_ids``` — if present —\nmust still be a list of integers or the request is rejected with\n```400```.\n", "operationId": "deleteLayerVersionTiles", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerVersionTilesDeleteRequest" } } } }, "responses": { "204": { "description": "Tiles marked for deletion." }, "400": { "description": "The version is not published, neither ```tile_ids``` nor ```all=true``` was provided, or ```tile_ids``` is not a list of integers.\n" }, "404": { "description": "Layer or version not found, the user lacks ```admin``` permission, or the layer version is not a raster layer.\n" } } } }, "/layers/{layer_id}/versions/{version_id}/doi/": { "get": { "summary": "Get Layer DOI", "tags": [ "Data Object Identifiers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getLayerDOI", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID.", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "The version ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DOI" } } } } } }, "post": { "summary": "Auto-Create or Set Layer DOI", "tags": [ "Data Object Identifiers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "createLayerDOI", "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "The layer ID.", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "The version ID.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDOIRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DOI" } } } }, "409": { "description": "CONFLICT — the version is not a draft, so a DOI cannot be created." } } } }, "/layers/{layer_id}/settings/": { "parameters": [ { "name": "layer_id", "in": "path", "required": true, "description": "ID of the layer or table", "schema": { "type": "integer" } } ], "get": { "summary": "Get layer settings", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:read" ] } ], "operationId": "getLayerSettings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerSettings" } } } } } }, "put": { "summary": "Update layer settings", "tags": [ "Layers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "layers:write" ] } ], "operationId": "putLayerSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerSettings" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerSettings" } } } } } } }, "/documents/": { "get": { "summary": "Returns a list of documents.", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:read" ] } ], "operationId": "getDocuments", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentsGet" } } } } } }, "post": { "summary": "Create document", "description": "Note that documents can only be created from sources with the data type `document`.", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "operationId": "createDocuments", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDocuments" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDocumentsResponse" } } } } } } }, "/documents/{id}/": { "get": { "summary": "Retrieve a document", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDocumentDetail", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetailsGet" } } } } } }, "put": { "summary": "Change the owner of a document", "description": "Change the owner (user or group) of a document. Ownership takes effect\nimmediately and is not tied to publishing a new version.\n", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "operationId": "changeDocumentOwner", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentOwnerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetailsGet" } } } } } }, "delete": { "summary": "Delete Documents", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "tags": [ "Documents" ], "operationId": "deleteDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NO CONTENT" } } } }, "/documents/{id}/versions/": { "get": { "summary": "List document versions", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:read" ] } ], "operationId": "getDocumentsVersions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDocumentsResponse" } } } } } }, "post": { "summary": "Create document version", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "operationId": "createDocumentVersion", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDocuments" } } } }, "responses": { "201": { "description": "OK" } } } }, "/documents/{id}/versions/{version}/": { "get": { "summary": "Retrieve document version.", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:read" ] } ], "operationId": "getDocumentVersionDetail", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "description": "Document version ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "put": { "summary": "Update document version", "tags": [ "Documents" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "operationId": "putDocumentsVersions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "description": "Document version ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete Document Version", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "tags": [ "Documents" ], "operationId": "deleteDocumentVersion", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "description": "Document version ID.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteDocumentVirsionDetail" } } } }, "responses": { "204": { "description": "NO CONTENT" }, "405": { "description": "Method Not Allowed — the version is not a deletable draft (it is not a draft, or it is currently publishing)." } } } }, "/documents/{id}/versions/{version}/import/": { "post": { "summary": "Publish document version", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "documents:write" ] } ], "tags": [ "Documents" ], "operationId": "publishDocumentVersion", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "description": "Document version ID.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created" } } } }, "/documents/{document_id}/versions/{version_id}/doi/": { "get": { "summary": "Get Document DOI", "tags": [ "Data Object Identifiers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDocumentDOI", "parameters": [ { "name": "document_id", "in": "path", "required": true, "description": "The document ID.", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "The version ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DOI" } } } } } }, "post": { "summary": "Auto-Create or Set Document DOI", "tags": [ "Data Object Identifiers" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "createDocumentDOI", "parameters": [ { "name": "document_id", "in": "path", "required": true, "description": "The document ID.", "schema": { "type": "integer" } }, { "name": "version_id", "in": "path", "required": true, "description": "The version ID.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDOIRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DOI" } } } }, "409": { "description": "CONFLICT — the version is not a draft, so a DOI cannot be created." } } } }, "/items/": { "get": { "summary": "List published catalog items", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItems", "parameters": [ { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Free-text search query." }, { "in": "query", "name": "sort", "schema": { "type": "string" }, "description": "Sort order, e.g. `name`, `created_at`, `popularity`. Prefix with `-` for descending.\n" }, { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Filter by one or more catalog item ids (repeatable)." }, { "in": "query", "name": "kind", "schema": { "type": "string" }, "description": "Filter by item kind (repeatable)." }, { "in": "query", "name": "category", "schema": { "type": "string" }, "description": "Filter by category key (repeatable)." }, { "in": "query", "name": "tag", "schema": { "type": "string" }, "description": "Filter by tag (repeatable)." }, { "in": "query", "name": "geotag", "schema": { "type": "string" }, "description": "Filter by geotag key (repeatable)." }, { "in": "query", "name": "license", "schema": { "type": "string" }, "description": "Filter by license (repeatable)." }, { "in": "query", "name": "public", "schema": { "type": "boolean" }, "description": "Filter by public/shared status." }, { "in": "query", "name": "is_starred", "schema": { "type": "boolean" }, "description": "Filter to items the user has starred." }, { "in": "query", "name": "is_pinned", "schema": { "type": "boolean" }, "description": "Filter to items the user has pinned." }, { "in": "query", "name": "created_at.before", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to items created before this time (ISO-8601)." }, { "in": "query", "name": "created_at.after", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to items created after this time (ISO-8601)." }, { "in": "query", "name": "updated_at.before", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to items updated before this time (ISO-8601)." }, { "in": "query", "name": "updated_at.after", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to items updated after this time (ISO-8601)." }, { "in": "query", "name": "from", "schema": { "type": "string" }, "description": "Filter by source context." }, { "in": "query", "name": "org", "schema": { "type": "string" }, "description": "Filter by organisation (repeatable)." }, { "in": "query", "name": "user", "schema": { "type": "string" }, "description": "Filter by owning user id, or `me` (repeatable)." }, { "in": "query", "name": "context", "schema": { "type": "string" }, "description": "Filter by context (repeatable)." }, { "in": "query", "name": "group", "schema": { "type": "string" }, "description": "Filter by owning group (repeatable)." }, { "in": "query", "name": "pt", "schema": { "type": "string" }, "description": "Point (`lon,lat`) for spatial filtering; pairs with `distance`." }, { "in": "query", "name": "distance", "schema": { "type": "integer" }, "description": "Distance in kilometres from `pt`." }, { "in": "query", "name": "geometry", "schema": { "type": "string" }, "description": "GeoJSON/WKT polygon for spatial filtering." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemList" } } } } } }, "post": { "summary": "Create catalog item", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemCreateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemDetail" } } } } } } }, "/items/latest/": { "get": { "summary": "List catalog items with latest versions", "description": "All the same filters and ordering as `/items/` apply.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemsLatest", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemList" } } } } } } }, "/items/{catalogitem_id}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "Get catalog item detail", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItem", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemDetail" } } } } } } }, "/items/{catalogitem_id}/versions/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "List catalog item versions", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemVersions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemVersionList" } } } } } }, "post": { "summary": "Create draft version", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemCreateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemDetail" } } } } } } }, "/items/{catalogitem_id}/versions/draft/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/versions/published/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "Redirect to published version", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemPublishedVersion", "responses": { "200": { "description": "The resolved published version detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemDetail" } } } }, "307": { "description": "Temporary redirect to the published version detail URL." } } } }, "/items/{catalogitem_id}/versions/publish/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ], "get": { "summary": "Get catalog item version detail", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemVersion", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemDetail" } } } } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/publish/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/datasources/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ], "get": { "summary": "List version datasources", "description": "Datasources for the version (used by 3D Tiles items).", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemVersionDatasources", "parameters": [ { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "list" ] }, "description": "Send `list` to inline the full datasource representation instead of summary objects.\n" } ], "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/attachments/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ], "get": { "summary": "List attachments", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemAttachments", "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Add attachment", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemAttachment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemAttachmentRequest" } } } }, "responses": { "201": { "description": "Created" } } }, "put": { "summary": "Replace attachments", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "putCatalogItemAttachments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemAttachmentRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/attachments/{document_id}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } }, { "name": "document_id", "in": "path", "required": true, "description": "The attachment document id.", "schema": { "type": "integer" } } ], "get": { "summary": "Get attachment detail", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemAttachment", "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/attachments/{document_id}/download/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } }, { "name": "document_id", "in": "path", "required": true, "description": "The attachment document id.", "schema": { "type": "integer" } } ], "get": { "summary": "Download attachment", "description": "Returns a 307 redirect to the attachment file.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemAttachmentDownload", "responses": { "200": { "description": "The attachment file contents.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "307": { "description": "Redirect to the attachment file." } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ], "get": { "summary": "List XML metadata", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemMetadata", "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Replace XML metadata", "description": "Parses, validates and replaces the version's native XML metadata.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "url_html": { "type": "string", "format": "uri" } } } } } } } }, "delete": { "summary": "Delete XML metadata", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "deleteCatalogItemMetadata", "responses": { "204": { "description": "No Content" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/simple/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ], "get": { "summary": "Get simplified metadata", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemMetadataSimple", "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/context/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/{data_type}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } }, { "name": "data_type", "in": "path", "required": true, "description": "The metadata data type.", "schema": { "type": "string" } } ], "get": { "summary": "Get metadata document", "description": "`data_type` is one of `iso`, `fgdc` or `dc`.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemMetadataType", "responses": { "200": { "description": "OK" } } }, "put": { "summary": "Update metadata document", "description": "`data_type` is one of `iso`, `fgdc` or `dc`.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "putCatalogItemMetadataType", "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/{data_type}/simple/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } }, { "name": "data_type", "in": "path", "required": true, "description": "The metadata data type.", "schema": { "type": "string" } } ], "get": { "summary": "Get simplified metadata for type", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemMetadataTypeSimple", "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/{data_type}/context/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } }, { "name": "data_type", "in": "path", "required": true, "description": "The metadata data type.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/versions/{catalogitem_version_id}/metadata/{data_type}/elementDefinition/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "catalogitem_version_id", "in": "path", "required": true, "description": "The catalog item version id.", "schema": { "type": "string" } }, { "name": "data_type", "in": "path", "required": true, "description": "The metadata data type.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/permissions/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/permissions/{owner_key}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "owner_key", "in": "path", "required": true, "description": "The permission owner key (e.g. \"user.123\" / \"group.45\").", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/permissions/{owner_key}/{permission}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "owner_key", "in": "path", "required": true, "description": "The permission owner key (e.g. \"user.123\" / \"group.45\").", "schema": { "type": "string" } }, { "name": "permission", "in": "path", "required": true, "description": "The permission name.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/star/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "post": { "summary": "Star catalog item", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemStar", "responses": { "204": { "description": "No Content" } } }, "delete": { "summary": "Unstar catalog item", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "deleteCatalogItemStar", "responses": { "204": { "description": "No Content" } } } }, "/items/{catalogitem_id}/pin/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "post": { "summary": "Pin catalog item", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemPin", "responses": { "204": { "description": "No Content" } } }, "delete": { "summary": "Unpin catalog item", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "deleteCatalogItemPin", "responses": { "204": { "description": "No Content" } } } }, "/items/{catalogitem_id}/feedback/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "Get contact-publisher details", "description": "Returns the publisher contact form details (object name, url and disclaimer). Returns 404 when feedback is disabled for the item.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemFeedback", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" } } } } } }, "404": { "description": "Feedback is disabled for this item." } } }, "post": { "summary": "Contact publisher", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemFeedback", "responses": { "202": { "description": "Accepted" }, "404": { "description": "Feedback is disabled for this item." } } } }, "/items/{catalogitem_id}/request-access/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "post": { "summary": "Request access", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "postCatalogItemRequestAccess", "responses": { "202": { "description": "Accepted" }, "409": { "description": "The caller already has access or a pending request." } } }, "delete": { "summary": "Cancel access request", "description": "Cancel the caller's pending access request for this item.", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "deleteCatalogItemRequestAccess", "responses": { "204": { "description": "No Content" }, "404": { "description": "No pending access request exists." } } } }, "/items/{catalogitem_id}/geotags/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "List geotags", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemGeotags", "responses": { "200": { "description": "OK" } } } }, "/items/{catalogitem_id}/client-styles/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "List client styles", "description": "Client-side styles saved against this catalog item. The style document is returned under `payload`.\n", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getCatalogItemClientStyles", "parameters": [ { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "list" ] }, "description": "Send `list` to inline the full client style representation instead of summary objects.\n" } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create client style", "description": "The style document is supplied under `payload`. A maximum of three active styles is allowed per catalog item.\n", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "postCatalogItemClientStyle", "responses": { "201": { "description": "Created" } } } }, "/items/{catalogitem_id}/client-styles/{pk}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "pk", "in": "path", "required": true, "description": "The client style id.", "schema": { "type": "integer" } } ], "get": { "summary": "Get client style", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getCatalogItemClientStyle", "responses": { "200": { "description": "OK" } } }, "put": { "summary": "Update client style", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "putCatalogItemClientStyle", "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete client style", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "deleteCatalogItemClientStyle", "responses": { "204": { "description": "No Content" } } } }, "/items/{catalogitem_id}/services/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } } ], "get": { "summary": "List catalog item services", "description": "See the [Services documentation](#tag/Services) for permissions and enable/disable rules.\n", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemServices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicesList" } } } } } } }, "/items/{catalogitem_id}/services/{service_id}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service id.", "schema": { "type": "string" } } ], "get": { "summary": "Get catalog item service detail", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:read" ] } ], "operationId": "getCatalogItemService", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } } } }, "put": { "summary": "Update catalog item service", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "putCatalogItemService", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUpdateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } } } }, "patch": { "summary": "Partially update catalog item service", "tags": [ "Catalog Items" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "items:write" ] } ], "operationId": "patchCatalogItemService", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUpdateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSerializer" } } } } } } }, "/items/{catalogitem_id}/services/{service_id}/permissions/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service id.", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/services/{service_id}/permissions/{owner_key}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service id.", "schema": { "type": "string" } }, { "name": "owner_key", "in": "path", "required": true, "description": "The permission owner key (e.g. \"user.123\" / \"group.45\").", "schema": { "type": "string" } } ] }, "/items/{catalogitem_id}/services/{service_id}/permissions/{owner_key}/{permission}/": { "parameters": [ { "name": "catalogitem_id", "in": "path", "required": true, "description": "The catalog item public id.", "schema": { "type": "string" } }, { "name": "service_id", "in": "path", "required": true, "description": "The service id.", "schema": { "type": "string" } }, { "name": "owner_key", "in": "path", "required": true, "description": "The permission owner key (e.g. \"user.123\" / \"group.45\").", "schema": { "type": "string" } }, { "name": "permission", "in": "path", "required": true, "description": "The permission name.", "schema": { "type": "string" } } ] }, "/licenses/": { "get": { "summary": "Get licenses", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Licenses" ], "operationId": "getLicenses", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseList" } } } } } }, "post": { "summary": "Create a new custom license", "description": "Note that only custom licenses can be created.", "security": [ { "SessionAuthentication": [] } ], "tags": [ "Licenses" ], "operationId": "postLicense", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLicenseRequest" } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseItemSerializer" } } } } } } }, "/licenses/{id}/": { "get": { "summary": "Fetch a single license", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Licenses" ], "operationId": "getSingleLicense", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The numeric ID of the license.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseItemSerializer" } } } } } }, "put": { "summary": "Update a custom license", "description": "Note that only custom licenses can be updated.", "security": [ { "SessionAuthentication": [] } ], "tags": [ "Licenses" ], "operationId": "updateLicense", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The numeric ID of the license.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLicenseRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseItemSerializer" } } } } } }, "delete": { "summary": "Delete a custom license", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Licenses" ], "operationId": "deleteLicense", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The numeric ID of the license.", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NO CONTENT" } } } }, "/coordinate-systems/": { "get": { "summary": "List available coordinate systems", "operationId": "listCoordinateSystems", "security": [ {}, { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Coordinate Systems" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoordinateSystemList" } } } } }, "parameters": [ { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/CoordinateSystemKind" } }, { "name": "q", "in": "query", "schema": { "type": "string", "description": "Free text search query", "example": "pacific+ocean" } } ] } }, "/coordinate-systems/{id}/": { "get": { "summary": "Retrieve information about a coordinate system", "operationId": "getCoordinateSystemDetail", "security": [ {}, { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "tags": [ "Coordinate Systems" ], "parameters": [ { "name": "id", "in": "path", "required": true, "example": "EPSG:4326", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoordinateSystem" } } } } } } }, "/sources/": { "get": { "summary": "List Sources", "description": "Returns a list of all the sources available to you.", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getSources", "parameters": [ { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "list", "list.permissions", "list.scans", "list.last_scan", "list.publisher" ] }, "description": "`list` returns the detailed source representation for each result. The `list.*` values additionally inline that field instead of linking to it, and can be combined (comma-separated) - see `/sources/{id}/` for what each one expands to.\n" }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Free-text search query (source name, description, tags)." }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ] }, "description": "Sort order. Defaults to `updated_at` (most recently scanned first), or relevance when `q` is given. For sources, `updated_at` is the start time of the last scan.\n" }, { "in": "query", "name": "id", "schema": { "type": "integer" }, "description": "Filter by source ID (repeatable)." }, { "in": "query", "name": "kind", "schema": { "type": "string", "enum": [ "arcgis", "wfs", "postgres", "cifs", "s3", "kart", "url", "web", "info", "upload" ] }, "description": "Filter by source type (repeatable)." }, { "in": "query", "name": "group", "schema": { "type": "integer" }, "description": "Filter by owning group ID (repeatable)." }, { "in": "query", "name": "user", "schema": { "type": "string" }, "description": "Filter by owning user public ID, or `me` (repeatable). Prefix with `-` to exclude.\n" }, { "in": "query", "name": "org", "schema": { "type": "string" }, "description": "Filter by organisation (repeatable). Prefix with `-` to exclude." }, { "in": "query", "name": "public", "schema": { "type": "boolean" }, "description": "Filter by public/shared status." }, { "in": "query", "name": "role", "schema": { "type": "string", "enum": [ "find", "view", "download", "admin" ] }, "description": "Only return sources the authenticated user holds this permission on. Defaults to `find`.\n" }, { "in": "query", "name": "category", "schema": { "type": "string" }, "description": "Filter by category URL, including descendants (repeatable)." }, { "in": "query", "name": "tag", "schema": { "type": "string" }, "description": "Filter by tag (repeatable)." }, { "in": "query", "name": "license", "schema": { "type": "string" }, "description": "Filter by license ID, or `true`/`false` for any/no license (repeatable).\n" }, { "in": "query", "name": "is_imported", "schema": { "type": "boolean" }, "description": "`true` returns fully-imported sources; `false` returns unimported and partially-imported ones.\n" }, { "in": "query", "name": "has_datasources", "schema": { "type": "boolean" }, "description": "Filter to sources that have (or have no) datasources." }, { "in": "query", "name": "has_metadata", "schema": { "type": "boolean" }, "description": "Filter to sources that have (or have no) XML metadata." }, { "in": "query", "name": "updatable", "schema": { "type": "boolean" }, "description": "Filter to sources with at least one updated datasource." }, { "in": "query", "name": "created_at.before", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to sources created before this time (ISO-8601)." }, { "in": "query", "name": "created_at.after", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to sources created after this time (ISO-8601)." }, { "in": "query", "name": "updated_at.before", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to sources last scanned before this time (ISO-8601)." }, { "in": "query", "name": "updated_at.after", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to sources last scanned after this time (ISO-8601)." }, { "in": "query", "name": "facets", "schema": { "type": "boolean" }, "description": "Return facet counts for the current filters instead of results - see [Faceting](#section/Getting-started/API-Features).\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sources" } } } } } }, "post": { "summary": "Create a Source", "description": "To create a source, post to this view.\n\n### Parameters\n* type: `string` (required). The type of source to create. Example: info. Choices: info upload cifs arcgis wfs postgres\n* name: `string` (required). The name of the new source.\n* group: `string|id`(optional)\n* user: `string|id` (optional). The group or user (at least one required) that owns the source, by ID or API URL.\n* url_remote: `string` (optional). The remote URL to the source, not required for info or uploadsources\n* options: object (optional). Refer to the source specific notes above.\n* scan_schedule: `string` (optional). A Cron expression specifying how frequently the source should be scanned. All normal cron values are supported but the ‘minutes’ value is currently ignored. Predefined scheduling definitions are supported except for \"@reboot\".\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "createSources", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createSources" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createSourcesResponse" } } } } } } }, "/sources/{id}/": { "get": { "summary": "Get source detail", "description": "Returns details of a source.", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getSourcesDetails", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "permissions", "scans", "last_scan", "publisher" ] }, "description": "Inlines these fields instead of linking to them (comma-separated for more than one):\n\n * `permissions` - the source's direct permissions. Requires the\n `admin` permission on the source; without it the field stays a URL.\n * `scans` - the 5 most recent scans, newest first.\n * `last_scan` - the most recent scan.\n * `publisher` - the owning group or user.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sources" } } } } } }, "put": { "summary": "Edit a source", "description": "Note that:\n\nYou can't change the type of a source.\nYou can't upload more files into an upload source. If you need to upload more files you should create a new source.\nThe following fields are editable (other fields will be ignored):\n* name\n* description\n* categories\n* `user` / `group`\n* scan_schedule\n* `options` (note: existing options will be preserved if they're not specified here)\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "editSource", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editSource" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editSourceResponse" } } } } } }, "delete": { "summary": "Delete a source", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [ "users:write" ] } ], "tags": [ "Data Sources" ], "operationId": "deleteSource", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "NO CONTENT" } } } }, "/sources/{id}/scans/": { "get": { "summary": "List scans", "tags": [ "Data Sources" ], "description": "Returns a list of scans for a source.\n\nNotable fields:\n\n`status` : The current status of this scan. Valid values are:\n\n`running`\n`completed`\n`cancelled`\n`error`\n`change_counts` : counts of datasources deleted, updated and added in this scan. This is only guaranteed to be present in completed scans. For other scans it may be null or the counts may all be 0.\n\n`last_activity_at` : when the scan last wrote to its log. Log output is flushed at least every 10 seconds while the scan is running, so a running scan whose `last_activity_at` is well in the past has stalled.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getSourceScans", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "list" ] }, "description": "Send `list` for the detailed scan representation (including `progress`) instead of the summary one.\n" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "running", "completed", "cancelled", "error" ] }, "description": "Filter by scan status." }, { "in": "query", "name": "sort", "schema": { "type": "string", "enum": [ "id", "-id", "started_at", "-started_at", "completed_at", "-completed_at" ] }, "description": "Sort order. Defaults to `-id` (newest first)." }, { "in": "query", "name": "started_at.before", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to scans started at or before this time (ISO-8601). The `started_at__before` spelling also works.\n" }, { "in": "query", "name": "started_at.after", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to scans started at or after this time (ISO-8601)." }, { "in": "query", "name": "started_at", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to scans started at exactly this time (ISO-8601)." }, { "in": "query", "name": "completed_at.before", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to scans completed at or before this time (ISO-8601)." }, { "in": "query", "name": "completed_at.after", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to scans completed at or after this time (ISO-8601)." }, { "in": "query", "name": "completed_at", "schema": { "type": "string", "format": "date-time" }, "description": "Filter to scans completed at exactly this time (ISO-8601)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceScans" } } } } } }, "post": { "summary": "Start scan", "description": "Starts a scan for this source. No post data is required.\n\nSupply `datasources` to rescan particular datasources instead of the\nwhole source.\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "startSourceScan", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/startSourceScan" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createSourcesResponse" } } } }, "409": { "description": "Conflict — another scan of this source is already running." } } } }, "/sources/{id}/scans/{scan}": { "get": { "summary": "Get scan detail", "description": "Information about a particular scan. This is the same as an item in the list view above, except it also includes a `progress` indicator, which is a float between 0 and 1. Progress is approximate.\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getSourceScanDetails", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "name": "scan", "in": "path", "required": true, "description": "The scan ID (an integer), or the literal value 'latest' to use the most recent scan.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceScanDetailsGet" } } } } } }, "delete": { "summary": "Cancel or delete scan", "description": "Cancels an in-progress scan.", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "cancelScan", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "name": "scan", "in": "path", "required": true, "description": "The scan ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "NO CONTENT" }, "409": { "description": "Conflict — the scan is finished or already cancelled." } } } }, "/sources/{id}/scans/{scan}/log/": { "get": { "summary": "Get scan log", "description": "Gets a log for a scan. By default this is returned as text/plain, but you can request JSON via the `Accept` header.", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getScanLog", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "name": "scan", "in": "path", "required": true, "description": "The scan ID (an integer), or the literal value 'latest' to use the most recent scan.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/sources/{id}/datasources/": { "get": { "summary": "List datasources", "description": "Lists datasources for this source.\n\nThe API for datasources is read-only. Datasources are updated by scanning your source. If you don't see what you expect here, check that your source has been scanned recently.\n\nResults are in `(source, path)` order. This list takes no filters or sort order; only pagination and the `Expand` header below.\n\nDatasource states\n\nEach datasource carries a `state`:\n\n* `new` — found by a scan but never imported into a layer or table. A datasource that is never imported stays `new` indefinitely.\n* `imported` — imported into at least one layer or table.\n* `updated` — changed at the source since it was last imported. Only set for datasources linked to a live layer or table; importing it again returns it to `imported`.\n* `pending` / `error` — uploads only: the file is still uploading or validating, or validation failed.\n* `deleted` — a scan no longer sees the datasource at the source.\n\nDeleted datasources are omitted from this list and from the datasource detail view. `deleted` only appears on a scan's datasource list and on layer version datasource lists.\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "listDatasources", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "in": "header", "name": "Expand", "required": false, "schema": { "type": "string", "enum": [ "list" ] }, "description": "Send `list` for the full datasource representation - the same fields as the datasource detail view below - instead of the summary one.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Datasources" } } } } } } }, "/sources/{id}/datasources/{datasource}/": { "get": { "summary": "Get datasource detail", "description": "Detailed information for a given datasource. Includes all the info shown in the list above, as well as much more information describing the datasource.\n\nField notes\n* `type` is the source type, not to be confused with `data_type`, `format` or `geometry_type`\n\n* `data_type` refers to the broad type of data. Different types of data require significantly different handling. Current data types are:\n\n * `table`\n * `vector`\n * `raster`\n * `grid`\n * `attribute-grid`\n* `format` is a string describing the media type of this datasource.\n\n* `geometry_type` describes the type of geometry in vector datasources. It is null for non-vector datasources. Possible values are:\n\n* `point`\n* `linestring`\n* `polygon`\n* `multipoint`\n* `multilinestring`\n* `multipolygon`\n* Spatial datasources may or may not have a known Coordinate Reference System (`crs`).\n* `extent` is a GeoJSON geometry. It may be null for aspatial datasources. The coordinate system for this geometry is the same as that in the `crs` field, which may not be known.\n* For vector and table datasources, `fields` is a list of JSON objects. It will be null for other datasources.\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDatasourceDetail", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "name": "datasource", "in": "path", "required": true, "description": "The datasource ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourceDetail" } } } } } } }, "/sources/{id}/datasources/{datasource}/metadata/": { "get": { "summary": "Get datasource metadata", "description": "Some datasources can have attached XML metadata. This is attached by the CIFS and Upload scanners, if a datasource has an `.xml` file with the same basename. For example:\n\n`my-points-with-metadata.geojson`\n`my-points-with-metadata.xml`\nAs with sources, datasource XML must be in one of these three formats:\n\n* ISO 19115/19139\n* FGDC CSDGM\n* Dublin Core\n\nResponse Body\n\n```\n\n \n Bob Jones and Associates\n hydro\n Some nice colourful aerial photos of the Auckland Harbour.\n 2013-01-01\n raster\n eng\n\n```\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDatasourceMetadata", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "name": "datasource", "in": "path", "required": true, "description": "The datasource ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasourceMetadata" } } } } } } }, "/sources/{id}/datasources/{datasource}/geotags/": { "get": { "summary": "List datasource geotags", "description": "The geotags covering a datasource's extent, as populated by scanning the source.\nEach `key` is a geotag URL that can be passed straight back as the `geotag`\nfilter of `/data/` and `/indexing/datasources/`.\n\nOnly indexed table and vector datasources are geotagged; for everything else\nthis list is empty.\n", "tags": [ "Data Sources" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] } ], "operationId": "getDatasourceGeotags", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "integer" } }, { "name": "datasource", "in": "path", "required": true, "description": "The datasource ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DatasourceGeotag" } } } } } } } }, "/services/query/v1/set/": { "servers": [ { "url": "https://{domain}", "variables": { "domain": { "default": "koordinates.com", "description": "Production API service" } } } ], "get": { "summary": "Get information from a set", "description": "Query a set (collection of layers) to find features near a point location. Returns results from all\nlayers in the set (both vector and raster). Results are returned as a JSON object with a `collectionQuery`\nproperty containing a `layers` array in the correct order. Each layer result includes the layer ID and title.\n\nSets also expose configurable data services; see the [Services documentation](#tag/Services) to list, enable/disable and manage permissions on them.\n", "tags": [ "Set Query" ], "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] }, { "URLTokenAuthentication": [] } ], "operationId": "getSet", "parameters": [ { "$ref": "#/components/parameters/KeyParameter" }, { "$ref": "#/components/parameters/SetParameter" }, { "$ref": "#/components/parameters/XParameter" }, { "$ref": "#/components/parameters/YParameter" }, { "$ref": "#/components/parameters/RadiusParameter" }, { "$ref": "#/components/parameters/GeometryParameter" }, { "$ref": "#/components/parameters/WithFieldNamesParameter" }, { "$ref": "#/components/parameters/PrecisionParameter" }, { "$ref": "#/components/parameters/CallbackParameter" }, { "$ref": "#/components/parameters/SetMaxResultsParameter" } ], "responses": { "200": { "description": "Successful response with data from all layers in the set", "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionQuery": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "collectionQuery" ] }, "set": { "type": "integer", "description": "Set ID" }, "x": { "type": "number", "description": "Query longitude" }, "y": { "type": "number", "description": "Query latitude" }, "layers": { "type": "array", "description": "Results from each layer in the set, in order", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Layer ID" }, "title": { "type": "string", "description": "Layer title" }, "type": { "type": "string", "enum": [ "VECTOR", "RASTER", "GRID" ], "description": "Layer data type" }, "results": { "oneOf": [ { "type": "array", "description": "Vector layer results (features with distance)" }, { "type": "object", "description": "Raster layer results (bands and status)" } ] } } } } } } }, "example": { "collectionQuery": { "type": "collectionQuery", "set": 101, "x": 174.77694, "y": -41.27831, "layers": [ { "id": 743, "title": "Electoral Districts", "type": "VECTOR", "results": [ { "__distance__": 0, "DISTRICT_NAME": "Wellington Central" } ] }, { "id": 1132, "title": "Elevation", "type": "GRID", "results": { "status": "ok", "bands": [ { "band": 1, "value": 45.2 } ] } } ] } } } } } } } } }, "/services/query/v1/raster.json": { "servers": [ { "url": "https://{domain}", "variables": { "domain": { "default": "koordinates.com", "description": "Production API service" } } } ], "get": { "summary": "Get information from grid or raster datasets", "description": "Query raster or grid layers to get band values at a point location. Returns band values if the point\nis within the layer extent. When querying multiple layers, results are returned as a JSON object\nwith layer IDs as keys.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] }, { "URLTokenAuthentication": [] } ], "tags": [ "Raster Query" ], "operationId": "getRaster", "parameters": [ { "$ref": "#/components/parameters/KeyParameter" }, { "$ref": "#/components/parameters/RasterLayerParameter" }, { "$ref": "#/components/parameters/XParameter" }, { "$ref": "#/components/parameters/YParameter" }, { "$ref": "#/components/parameters/CallbackParameter" } ], "responses": { "200": { "description": "Successful response with raster data", "content": { "application/json": { "schema": { "type": "object", "properties": { "rasterQuery": { "type": "object", "description": "Results grouped by layer ID", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "rasterQuery" ] }, "layer": { "type": "integer", "description": "Layer ID" }, "x": { "type": "number", "description": "Query longitude" }, "y": { "type": "number", "description": "Query latitude" }, "status": { "type": "string", "enum": [ "ok", "outside-extent", "not-available" ], "description": "Query status" }, "bands": { "type": "array", "description": "Band values at the query point (only present if status=ok)", "items": { "type": "object", "properties": { "band": { "type": "integer", "description": "Band number" }, "value": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Band value at the query point" } } } } } } } }, "example": { "rasterQuery": { "1132": { "type": "rasterQuery", "layer": 1132, "x": 174.77694, "y": -41.27831, "status": "ok", "bands": [ { "band": 1, "value": 245.5 } ] }, "1145": { "type": "rasterQuery", "layer": 1145, "x": 174.77694, "y": -41.27831, "status": "outside-extent" } } } } } } } } } }, "/services/query/v1/vector.json": { "servers": [ { "url": "https://{domain}", "variables": { "domain": { "default": "koordinates.com", "description": "Production API service" } } } ], "get": { "summary": "Get information from vector datasets", "description": "Query vector layers to find features near a point location. Returns features within the specified radius,\nordered by distance from the query point. When querying multiple layers, results are returned as a JSON\nobject with layer IDs as keys.\n", "security": [ { "SessionAuthentication": [] }, { "HeaderTokenAuthentication": [] }, { "URLTokenAuthentication": [] } ], "tags": [ "Vector Query" ], "operationId": "getVector", "parameters": [ { "$ref": "#/components/parameters/KeyParameter" }, { "$ref": "#/components/parameters/VectorLayerParameter" }, { "$ref": "#/components/parameters/XParameter" }, { "$ref": "#/components/parameters/YParameter" }, { "$ref": "#/components/parameters/VectorMaxResultsParameter" }, { "$ref": "#/components/parameters/RadiusParameter" }, { "$ref": "#/components/parameters/GeometryParameter" }, { "$ref": "#/components/parameters/WithFieldNamesParameter" }, { "$ref": "#/components/parameters/PrecisionParameter" }, { "$ref": "#/components/parameters/CallbackParameter" } ], "responses": { "200": { "description": "Successful response with feature data", "content": { "application/json": { "schema": { "type": "object", "properties": { "vectorQuery": { "type": "object", "description": "Results grouped by layer ID", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vectorQuery" ] }, "layer": { "type": "integer", "description": "Layer ID" }, "x": { "type": "number", "description": "Query longitude" }, "y": { "type": "number", "description": "Query latitude" }, "results": { "type": "array", "description": "Features found within the search radius", "items": { "type": "object", "properties": { "__distance__": { "type": "integer", "description": "Distance in meters from the query point" }, "__geometry__": { "type": "object", "description": "GeoJSON geometry (only included if geometry=true)" } } } } } } } }, "example": { "vectorQuery": { "743": { "type": "vectorQuery", "layer": 743, "x": 174.77694, "y": -41.27831, "results": [ { "__distance__": 0, "OBJECTID": 12345, "NAME": "Example Feature" }, { "__distance__": 523, "OBJECTID": 12346, "NAME": "Another Feature" } ] } } } } } } } } } } }, "components": { "securitySchemes": { "HeaderTokenAuthentication": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Simple HTTP header token based authentication.\nClients should authenticate by passing the token key in the \"Authorization\" HTTP header, prepended with the string \"key \". For example:\n\n Authorization: key abcdef0123456789abcdef0123456789\n" }, "URLTokenAuthentication": { "type": "apiKey", "in": "query", "name": "key", "description": "Simple URL token based authentication.\n**Note:** despite `in: query` above (OpenAPI cannot express this location), the key is **not** a query-string parameter. It is passed as a matrix-style path segment immediately after `/services`, in the form `;key=`. For example:\n\n GET /services;key=abcdef0123456789abcdef0123456789/wmts/1.0.0/WMTSCapabilities.xml\n" }, "SessionAuthentication": { "type": "apiKey", "in": "cookie", "name": "sessionid", "description": "Cookie based session authentication as provided by browser-based login flows. Most APIs are available with session authentication. Scopes are not required. APIs intended for use only within the Koordinates.com site or customer portals are *only* available with session authentication. Not recommended for external usage.\n" }, "BearerAuthToken": { "type": "apiKey", "in": "header", "name": "bearer", "description": "Bearer auth token as supplied by Koordinates ID. This is used by Koordinates for some internal services and in is not available for public use at this time.\n" } }, "schemas": { "Group": { "type": "object", "properties": { "id": { "type": "number" }, "url": { "type": "string", "format": "url" }, "name": { "type": "string" }, "country": { "type": "string" }, "org": { "type": "string" }, "type": { "type": "string", "enum": [ "normal", "default", "members" ] }, "access_requests_enabled": { "type": "boolean" } } }, "ListGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "RelatedUserSerializer": { "type": "object", "properties": { "id": { "type": "integer", "example": 482 }, "url": { "type": "string", "format": "url", "example": "https://example.koordinates.com/services/api/v1/users/482/" }, "first_name": { "type": "string", "example": "Jennifer" }, "last_name": { "type": "string", "example": "Exampleton" }, "country": { "type": "string", "example": "US" }, "geotag": { "type": "string", "example": "global/oceania/new-zealand" }, "email": { "type": "string", "example": "jennifer.exampleton@example.com" }, "is_locked": { "type": "boolean", "example": false }, "is_site_admin": { "type": "boolean", "example": false }, "seat_type": { "type": "string", "example": "none", "enum": [ "none", "paid" ] }, "date_joined": { "type": "string", "example": "2020-05-16T23:37:45.632286Z" }, "is_verified": { "type": "boolean", "example": true, "description": "`true` if the user has verified their email address.\n" }, "is_remote_auth": { "type": "boolean", "example": false, "description": "`true` if the user's Koordinates ID is linked to a 3rd party authorization service such as GSuite or Azure AD. This user cannot edit their profile information directly from Koordinates.\n" }, "is_mfa_enabled": { "type": "boolean", "example": false, "description": "`true` if the user has MFA enabled on their account.\n" } } }, "GroupUserPermission": { "type": "object", "properties": { "id": { "type": "string", "example": "user.99999" }, "user": { "type": "object", "$ref": "#/components/schemas/RelatedUserSerializer" }, "permission": { "type": "string", "enum": [ "view", "manage_data", "admin" ], "example": "view", "description": "Valid options can be determined via an OPTIONS request. Note that `view` grants the permission to view and download data from the group.\n" }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/groups/{group-id}/permissions/user.9999/" } } }, "GroupUserPermissionList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/GroupUserPermission" } }, "PutPostGroupUserPermission": { "type": "object", "properties": { "permission": { "type": "string", "enum": [ "view", "manage_data", "admin" ] }, "user": { "type": "number", "example": 99999 } } }, "PatchGroupUserPermission": { "type": "object", "properties": { "action": { "type": "string", "example": "update", "enum": [ "create", "update", "delete" ] }, "value": { "type": "object", "properties": { "permission": { "type": "string", "enum": [ "view", "manage_data", "admin" ], "example": "view" }, "user": { "type": "number", "example": 99999 } } }, "url": { "type": "string", "example": "https://{domain}/services/api/v1/groups/{group-id}/permissions/user.99999/", "description": "Required for `update` and `delete` actions.\n" } } }, "PatchGroupUserPermissionListRequest": { "type": "array", "minimum": 1, "items": { "$ref": "#/components/schemas/PatchGroupUserPermission" } }, "GroupAccessRequest": { "type": "object", "properties": { "id": { "type": "number", "example": 5 }, "url": { "type": "string", "format": "url", "example": "https://example.koordinates.com/groups/432/access-requests/4241/" }, "created_at": { "type": "string", "example": "2020-05-16T23:37:45.632286Z" } } }, "UserListSerializer": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedUserSerializer" } }, "UserContextItem": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "context": { "type": "string" }, "role": { "type": "string" }, "domain": { "type": "string" }, "org": { "type": "object" }, "flags": { "type": "object" }, "logo": { "type": "string", "format": "url" }, "background_color": { "type": "string", "example": "1e1b25" } } }, "UserContextList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/UserContextItem" } }, "OrgSerializer": { "type": "object", "properties": { "id": { "type": "string", "example": "o9xzyQC27q13FwT" }, "name": { "type": "string", "example": "Example Org" }, "url": { "type": "string", "format": "url", "example": "https://example.koordinates.com/services/api/v1.x/orgs/o9xzyQC27q13FwT/\"" }, "country": { "type": "string", "example": "US" }, "website": { "type": "string", "format": "url", "example": "https://example.com" }, "logo_owner_url": { "type": "string", "format": "url" }, "logo_square_url": { "type": "string", "format": "url" }, "slug": { "type": "string", "example": "example-org" } } }, "LoggedInUserSerializer": { "type": "object", "properties": { "id": { "type": "integer", "example": 482 }, "url": { "type": "string", "format": "url", "example": "https://example.koordinates.com/services/api/v1/users/482/" }, "first_name": { "type": "string", "example": "Jennifer" }, "last_name": { "type": "string", "example": "Exampleton" }, "country": { "type": "string", "example": "US" }, "email": { "type": "string", "example": "jennifer.exampleton@example.com" }, "is_locked": { "type": "boolean", "example": false }, "is_site_admin": { "type": "boolean", "example": false }, "seat_type": { "type": "string", "example": "none" }, "date_joined": { "type": "string", "example": "2020-05-16T23:37:45.632286Z" }, "avatar_url": { "type": "string", "format": "url" }, "capabilities": { "type": "object", "properties": { "administer_data": { "type": "boolean" }, "enable_kart_clone": { "type": "boolean" }, "can_see_repodatasets": { "type": "boolean" }, "can_see_site_tickets": { "type": "boolean" }, "can_manage_own_tickets": { "type": "boolean" }, "can_view_reports": { "type": "boolean" } } }, "contexts": { "$ref": "#/components/schemas/UserContextList" }, "remote_auth": { "type": "boolean", "example": false, "description": "`true` if the user's Koordinates ID is linked to a 3rd party authorization service such as GSuite or Azure AD. This user cannot edit their profile information directly from Koordinates.\n" }, "remote_auth_org": { "description": "The organisation that manages the external identity provider for this user.\n", "$ref": "#/components/schemas/OrgSerializer" }, "locale": { "type": "string", "example": "en-US" }, "geoip": { "type": "object", "properties": { "country_code": { "type": "string", "example": "AU" }, "state_code": { "type": "string" }, "name": { "type": "string", "example": "Australia" }, "key": { "type": "string", "example": "global/australia/australia" } } }, "is_authenticated": { "type": "boolean", "example": true }, "notification_preferences": { "type": "object", "properties": { "email_when_download_ready": { "type": "boolean", "example": true } } } } }, "RepoItemSerializer": { "type": "object", "properties": { "id": { "type": "string" }, "full_name": { "type": "string" }, "url": { "type": "string", "format": "url" }, "clone_location_ssh": { "type": "string" }, "clone_location_https": { "type": "string" } } }, "RepoList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoItemSerializer" } }, "RepoCreateRequest": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ] }, "RepoCloneSizeSerializer": { "type": "object", "properties": { "pack_size_bytes": { "type": "number", "example": 1234567890, "description": "Estimate of the size (in bytes) of the pack objects to be received. This is usually roughly equivalent to the size of the repository itself, excluding the working copy.\n" }, "working_copy_size_bytes": { "type": "number", "example": 1234567890, "description": "Estimate of the size (in bytes) of the working copy that would be created by cloning the repository, excluding the size of the repository itself.\n" }, "spatial_filter_ratio": { "type": "number", "example": 0.250071, "description": "Optional. The approximate overlap of the specified spatial-filter with the extent of the data in the repository, as a fraction (ie 0.25 means 25% of the data's extent is covered by the spatial filter). This estimates the effectiveness of the spatial filter at saving bandwidth - a number near 0 means most data will be filtered out, and a number near 1 means most data will still be sent. This is for added context only - the pack_size_bytes and working_copy_size_bytes have already been adjusted, they do not need to be adjusted further using this number. If this field is not present, no spatial-filter was applied - either no spatial-filter was specified, or, the spatial-filter could not be applied to the estimate in a timely manner.\n" } } }, "RepoBranch": { "type": "object", "properties": { "name": { "type": "string", "example": "master" }, "target": { "type": "string", "example": "e67a159dce20ccfb268e975d92f88a4d64a91d27" }, "shorthand": { "type": "string", "example": "master" } } }, "RepoBranchList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoBranch" } }, "RepoCommit": { "type": "object", "properties": { "commit": { "type": "string", "example": "e67a159dce20ccfb268e975d92f88a4d64a91d27" }, "abbrevCommit": { "type": "string", "example": "e67a159" }, "message": { "type": "string", "example": "Updated this api documentation" }, "authorName": { "type": "string", "example": "Jane Doe" }, "authorEmail": { "type": "string", "example": "jane.doe@example.com" }, "authorTime": { "type": "string", "example": "2021-07-07T03:50:42Z" }, "authorTimeOffset": { "type": "string", "example": "+01:00" }, "committerName": { "type": "string", "example": "Jane Doe" }, "committerEmail": { "type": "string", "example": "jane.doe@example.com" }, "committerTime": { "type": "string", "example": "2021-07-07T03:50:42Z" }, "committerTimeOffset": { "type": "string", "example": "+01:00" }, "parents": { "type": "array", "items": { "type": "string" } }, "abbrevParents": { "type": "array", "items": { "type": "string" } }, "refs": { "type": "array", "items": { "type": "string" } }, "featureChangeCounts": { "description": "Only present when the log was requested with `with-change-counts`. For each dataset\nthis commit changed, how many features (or tiles, for point cloud and raster\ndatasets) it inserted, updated and deleted relative to its first parent, plus\n`features`: how many that dataset contains at this commit.\nChange types with a count of zero are omitted, so a missing key means zero.\nDatasets this commit didn't change are omitted entirely - so a metadata-only\ncommit reports nothing here, not even dataset sizes. `features` is also absent\nfor a dataset this commit deleted.\n", "type": "object", "additionalProperties": { "type": "object", "properties": { "inserts": { "type": "integer" }, "updates": { "type": "integer" }, "deletes": { "type": "integer" }, "features": { "type": "integer" } } }, "example": { "property/boundaries": { "inserts": 5, "updates": 2, "deletes": 1, "features": 8231 } } } } }, "RepoDatasetImportSerializer": { "type": "object", "properties": { "path": { "type": "string", "example": "path/to/dataset" }, "datasources": { "type": "array", "items": { "type": "string" } }, "data_type": { "type": "string", "enum": [ "VECTOR", "RASTER", "GRID", "POINTCLOUD", "TABLE" ] }, "categories": { "type": "array", "items": { "type": "string", "maxItems": 1 } }, "tags": { "type": "array", "items": { "type": "string" } }, "license": { "type": "string" }, "metadata": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "string" } }, "strategy": { "type": "string", "enum": [ "update-existing", "replace-existing" ] } } }, "CommitOid": { "type": "string", "example": "42cd7929aa9aaca1782c6e75f552459ca41a7c66" }, "RepoImport": { "type": "object", "properties": { "url": { "type": "string" }, "message": { "type": "string" }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/RepoDatasetImportSerializer", "minItems": 1 } }, "ref": { "type": "string" }, "state": { "type": "string", "enum": [ "WORKING", "COMPLETED", "ERROR", "CANCELLED" ] }, "progress": { "type": "number", "format": "float", "minimum": 0, "maximum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "commit_oid": { "$ref": "#/components/schemas/CommitOid" }, "author_email": { "type": "string", "format": "email" } } }, "RepoImportList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoImport" } }, "RepoImportCreateRequest": { "type": "object", "properties": { "message": { "type": "string", "description": "A commit message to associate with the import" }, "ref": { "type": "string", "description": "The branch or tag to import to" }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/RepoDatasetImportSerializer" } } } }, "RepoLog": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoCommit" } }, "RepoDataset": { "type": "object", "properties": { "id": { "type": "string", "example": "dtV9pqYL3RtF9GK" }, "repository": { "type": "string", "format": "url", "example": "https://koordinates.com/services/api/v1/repos/my-publisher-name/my-repo/" }, "path": { "type": "string", "description": "Path of the dataset inside the Kart repo", "example": "property/boundaries" }, "url": { "type": "string", "format": "url", "example": "https://koordinates.com/services/api/v1/repos/my-publisher-name/my-repo/tree/main^:property/boundaries" }, "title": { "type": "string", "example": "Property Boundaries" }, "updated_at": { "description": "When this dataset was last updated.", "type": "string", "format": "date-time" }, "updated_at_commit": { "description": "The commit at which this dataset was last updated.", "type": "string", "example": "42cd7929aa9aaca1782c6e75f552459ca41a7c66" }, "ref": { "description": "The ref or commit hash this dataset was found at", "type": "string", "example": "42cd7929aa9aaca1782c6e75f552459ca41a7c66" }, "type": { "type": "string", "example": "layer", "enum": [ "layer" ] }, "kind": { "type": "string", "example": "vector", "enum": [ "vector", "pointcloud", "raster" ] }, "public_access": { "type": "string", "example": "download" }, "settings": { "type": "object", "example": {} }, "user_permissions": { "type": "array", "items": { "type": "string", "enum": [ "find", "view", "download", "write", "admin" ] }, "example": [ "find", "view", "download" ] } } }, "RepoDatasetList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoDataset" } }, "CoordinateSystemKind": { "type": "string", "enum": [ "geographic 2D", "geocentric", "geographic 3D", "projected", "vertical", "compound" ] }, "CoordinateSystem": { "type": "object", "properties": { "id": { "type": "string", "example": "EPSG:4326" }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/coordinate-systems/EPSG:4326/" }, "name": { "type": "string", "example": "WGS 84" }, "kind": { "$ref": "#/components/schemas/CoordinateSystemKind" }, "unit_horizontal": { "type": "string", "example": "degree", "nullable": true, "description": "Null for vertical coordinate systems" }, "unit_vertical": { "type": "string", "example": null, "nullable": true, "description": "Non-null for vertical and compound coordinate systems; null otherwise" }, "url_external": { "type": "string", "format": "url", "example": "https://epsg.io/4326" }, "srid": { "type": "integer", "example": 4326, "nullable": true, "deprecated": true, "description": "Integer identifier for EPSG coordinate systems only. Use `id` instead" }, "definition": { "type": "string", "example": "GEOGCRS[\"WGS 84\",DATUM[\"World Geodetic System 1984\",ELLIPSOID[\"WGS 84\",6378137,298.257223563,LENGTHUNIT[\"metre\",1]]],PRIMEM[\"Greenwich\",0,ANGLEUNIT[\"degree\",0.0174532925199433]],CS[ellipsoidal,2],AXIS[\"geodetic latitude (Lat)\",north,ORDER[1],ANGLEUNIT[\"degree\",0.0174532925199433]],AXIS[\"geodetic longitude (Lon)\",east,ORDER[2],ANGLEUNIT[\"degree\",0.0174532925199433]],USAGE[SCOPE[\"Horizontal component of 3D system.\"],AREA[\"World.\"],BBOX[-90,-180,90,180]],ID[\"EPSG\",4326]]\n" } } }, "Point3D": { "type": "array", "description": "Point in 3D space", "externalDocs": { "description": "GeoJSON spec", "url": "http://geojson.org/geojson-spec.html#id2" }, "minItems": 2, "maxItems": 3, "items": { "type": "number" } }, "MultiPolygon": { "type": "object", "description": "MultiPolygon geometry", "externalDocs": { "description": "GeoJSON spec", "url": "http://geojson.org/geojson-spec.html#id6" }, "properties": { "type": { "type": "string", "enum": [ "MultiPolygon" ] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Point3D" } } } } } }, "GriddedExtent": { "type": "string", "description": "A hex-encoded WKB string describing a multipolygon covering a tile or dataset.", "example": "01030000000100000015000000874575C6F9D76540B93C039AC86B42C0A07E7718F8D76540CBF62CAEA16A42C099920439F8D7654001A6EDCB9E6A42C0754F099EF8D765405D1783549C6A42C0A2E4FC37F9D765401D6006A99A6A42C0DCAE32EFF9D765403C78340B9A6A42C0CA4AF99555D8654063DE95A1946A42C01708794C56D86540858DD926956A42C0550789E856D865403A080EB8966A42C05D2DA55257D86540DCD5BE18996A42C0F049D07A57D8654018BD33ED9B6A42C079378D2B59D86540709696D8C26B42C0046F050B59D8654059FFEABAC56B42C0B21D02A658D86540817C6D32C86B42C092910C0C58D8654087DCFCDDC96B42C0B6CFD25457D865401B49D67BCA6B42C0260D4DABFBD765408A4FE8E5CF6B42C06D0EC9F4FAD7654037869E60CF6B42C0E4A8B658FAD7654019FB57CFCD6B42C0C4759BEEF9D7654008C88E6ECB6B42C0874575C6F9D76540B93C039AC86B42C0" }, "PointCloudClassification": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Classification identifier as per the LAS spec." }, "name": { "type": "string", "example": "Low Vegetation", "description": "Classification name as per the LAS spec. Custom classifications may have names, or may use the name 'Reserved'" }, "count": { "type": "integer", "minimum": 0, "example": 1234567, "description": "The number of points in this tile/dataset which have this classification." }, "is_custom": { "type": "boolean", "example": false, "description": "Whether this classification is a custom (user-defined or reserved) classification according to the LAS spec." } } }, "PointCloudClassificationFlag": { "type": "object", "properties": { "name": { "type": "string", "example": "Synthetic", "enum": [ "Synthetic", "Key-point", "Withheld", "Overlap" ] }, "count": { "type": "integer", "minimum": 0, "example": 1234567, "description": "The number of points in this tile/dataset which have this classification flag set." } } }, "RepoDatasetDetail": { "type": "object", "properties": { "id": { "type": "string", "example": "dtV9pqYL3RtF9GK" }, "repository": { "type": "string", "format": "url", "example": "https://koordinates.com/services/api/v1/repos/my-publisher-name/my-repo/" }, "path": { "type": "string", "description": "Path of the dataset inside the Kart repo", "example": "property/boundaries" }, "url": { "type": "string", "format": "url", "example": "https://koordinates.com/services/api/v1/repos/my-publisher-name/my-repo/tree/main^:property/boundaries" }, "title": { "type": "string", "example": "Property Boundaries" }, "updated_at": { "description": "When this dataset was last updated.", "type": "string", "format": "date-time" }, "updated_at_commit": { "description": "The commit at which this dataset was last updated.", "type": "string", "example": "42cd7929aa9aaca1782c6e75f552459ca41a7c66" }, "ref": { "description": "The ref or commit hash this dataset was found at", "type": "string", "example": "42cd7929aa9aaca1782c6e75f552459ca41a7c66" }, "type": { "type": "string", "example": "layer", "enum": [ "layer" ] }, "kind": { "type": "string", "example": "vector", "enum": [ "vector", "pointcloud", "raster" ] }, "public_access": { "type": "string", "example": "download" }, "settings": { "type": "object", "example": {} }, "user_permissions": { "type": "array", "items": { "type": "string", "enum": [ "find", "view", "download", "write", "admin" ] }, "example": [ "find", "view", "download" ] }, "created_at": { "description": "When this dataset was first created.", "type": "string", "format": "date-time" }, "created_at_commit": { "description": "The commit which created this dataset.", "type": "string", "example": "42cd7929aa9aaca1782c6e75f552459ca41a7c66" }, "description": { "type": "string", "format": "markdown", "example": "This dataset contains *property boundaries* for privately owned titles." }, "description_html": { "type": "string", "format": "html", "example": "

This dataset contains property boundaries for privately owned titles.

" }, "group": { "$ref": "#/components/schemas/Group" }, "data": { "type": "object", "properties": { "storage": { "type": "string", "example": "kart" }, "crs": { "$ref": "#/components/schemas/CoordinateSystem" }, "primary_key_fields": { "type": "array", "items": { "type": "string" }, "example": [ "id" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "GEOMETRY" }, "type": { "type": "string", "example": "geometry" } } } }, "feature_count": { "type": "integer", "example": 7001234 }, "point_count": { "type": "integer", "example": 99123456789, "description": "The number of points or vertices in this dataset." }, "extent": { "$ref": "#/components/schemas/MultiPolygon" }, "gridded_extent": { "$ref": "#/components/schemas/GriddedExtent" }, "geometry_type": { "type": "string", "example": "point" }, "geometry_field": { "type": "array", "items": {}, "example": "GEOMETRY, WKT, [X, Y], null" }, "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/PointCloudClassification" }, "description": "Counts of the classifications present in this dataset (for pointcloud datasets only)", "externalDocs": { "description": "LAS 1.4 spec", "url": "https://www.asprs.org/wp-content/uploads/2010/12/LAS_1_4_r13.pdf" } }, "classification_flags": { "type": "array", "items": { "$ref": "#/components/schemas/PointCloudClassificationFlag" }, "minItems": 4, "maxItems": 4, "description": "Counts of the classification flags present in this dataset.", "externalDocs": { "description": "LAS 1.4 spec", "url": "https://www.asprs.org/wp-content/uploads/2010/12/LAS_1_4_r13.pdf" } }, "point_density_sqm": { "type": "number", "example": 12345.6789, "description": "An estimate of the density of this dataset (number of points per square metre)" } } }, "tags": { "type": "array", "example": [] } } }, "RepoDatasetMeta": { "type": "object", "properties": { "title": { "type": "string", "example": "Property Boundaries" }, "description": { "type": "string", "example": "This dataset contains *property boundaries* for privately owned titles." }, "tags.json": { "type": "array", "items": { "type": "string" }, "example": [ "New Zealand", "Cadastral" ] }, "schema.json": { "type": "array", "items": { "type": "object" }, "example": [ { "name": "Intensity", "dataType": "integer", "size": 16, "unsigned": true } ] } }, "additionalProperties": true }, "RepoMeta": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RepoDatasetMeta" }, "example": { "property/boundaries": { "title": "Property Boundaries", "description": "This dataset contains *property boundaries* for privately owned titles.", "tags": [], "schema.json": [ { "name": "Intensity", "dataType": "integer", "size": 16, "unsigned": true } ] } } }, "CommitOidAndAuthorDate": { "type": "object", "properties": { "oid": { "$ref": "#/components/schemas/CommitOid" }, "author_date": { "type": "string", "format": "date-time" } } }, "RepoPointCloudTile": { "type": "object", "properties": { "name": { "type": "string", "example": "auckland_1_1.copc.laz" }, "point_count": { "type": "integer", "example": 12345 }, "oid": { "type": "string", "example": "sha256:add2d011a19b39c0c8d70ed2313ad4955b1e0faf9a24394ab1a103930580a267" }, "source_oid": { "type": "string", "example": "sha256:d89966fb10b30d6987955ae1b97c752ba875de89da1881e2b05820878d17eab9" }, "extent": { "$ref": "#/components/schemas/MultiPolygon" }, "gridded_extent": { "$ref": "#/components/schemas/GriddedExtent" }, "first_commit": { "$ref": "#/components/schemas/CommitOidAndAuthorDate" }, "last_commit": { "$ref": "#/components/schemas/CommitOidAndAuthorDate" }, "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/PointCloudClassification" }, "description": "Counts of the classifications present in this tile's points.", "externalDocs": { "description": "LAS 1.4 spec", "url": "https://www.asprs.org/wp-content/uploads/2010/12/LAS_1_4_r13.pdf" } }, "classification_flags": { "type": "array", "items": { "$ref": "#/components/schemas/PointCloudClassificationFlag" }, "minItems": 4, "maxItems": 4, "description": "Counts of the classification flags present in this tile's points.", "externalDocs": { "description": "LAS 1.4 spec", "url": "https://www.asprs.org/wp-content/uploads/2010/12/LAS_1_4_r13.pdf" } }, "point_density_sqm": { "type": "number", "example": 12345.6789, "description": "An estimate of the density of this tile (number of points per square metre)" } } }, "RepoQueryTilesResponse": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoPointCloudTile" } }, "RepoPointCloudPoint": { "type": "object", "properties": { "X": { "type": "number", "example": 79.3758 }, "Y": { "type": "number", "example": -35.2354 }, "Z": { "type": "number", "example": 2.50071 }, "Intensity": { "type": "number", "example": 0 }, "ReturnNumber": { "type": "number", "example": 1 }, "NumberOfReturns": { "type": "number", "example": 2 }, "ScanDirectionFlag": { "type": "number", "example": 0 }, "EdgeOfFlightLine": { "type": "number", "example": 0 }, "Classification": { "type": "number", "example": 12 }, "ScanAngleRank": { "type": "number", "example": -15 }, "UserData": { "type": "number", "example": 0 }, "PointSourceId": { "type": "number", "example": 4 }, "GpsTime": { "type": "number", "description": "Optional", "example": 62242510.31 }, "ScanChannel": { "type": "number", "description": "Optional", "example": 0 }, "ClassFlags": { "type": "number", "description": "Optional", "example": 0 }, "Red": { "type": "number", "description": "Optional", "example": 25 }, "Green": { "type": "number", "description": "Optional", "example": 182 }, "Blue": { "type": "number", "description": "Optional", "example": 41 }, "Infrared": { "type": "number", "description": "Optional", "example": 127 } } }, "RepoQueryPointsResponse": { "type": "object", "properties": { "tiles": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoPointCloudTile" } }, "points": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/RepoPointCloudPoint" } } } }, "ExportItemSerializer": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "name": { "type": "string" }, "created_at": { "type": "string", "example": "2020-05-16T23:37:45.632286Z" }, "state": { "type": "string", "description": "- **processing**: the export is being created and will be available for download soon. If the export is processing, the download_url will be null.\n- **cancelled**: the export was processing but has been cancelled before it was completed.\n- **error**: there was an error during the creation of the export.\n- **complete**: the export has finished processing and is available for download at the location provided in download_url.\n- **gone**: the export was completed successfully but has since been removed or has expired from the system.\n", "enum": [ "complete", "processing", "cancelled", "error", "gone" ] }, "url": { "type": "string", "format": "url" }, "download_url": { "type": "string", "format": "url" } } }, "ExportList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/ExportItemSerializer" } }, "ExportDatasetItem": { "type": "object", "properties": { "item": { "type": "string", "description": "A URL to a layer, table or indexed datasource to export. An indexed datasource is named by its URL under its source, eg `/sources/{source_id}/datasources/{id}/`\n", "format": "url", "example": "https://{domain}/services/api/v1/layers/88131/" }, "color": { "type": "string", "example": "#003399", "description": "Specifies a color to render this layer in KML or PDF exports. Ignored for raster or aspatial datasets, and ignored for other formats." }, "tiles": { "type": "array", "items": { "type": "string", "example": "2017_BL32_1000_1323" }, "description": "A list of tile names to export, for tiled (raster, grid & pointcloud) datasets. If omitted, all tiles are exported. Ignored for non-tiled datasets.\n" }, "raster_resolution_multiplier": { "type": "number", "example": 1, "enum": [ 1, 2, 4 ], "description": "Specifies the resolution to render this layer for raster exports. Introduced in v1.x." }, "include_raster_tab": { "type": "boolean", "default": true, "description": "Whether to include MapInfo .tab files with raster tiles in this layer. Introduced in v1.x." }, "include_geometry_field": { "type": "boolean", "default": true, "description": "Whether to include geometry data in this layer for CSV exports. Introduced in v1.x." }, "include_hatching": { "type": "boolean", "default": false, "description": "Whether to include a hatch pattern in this layer for DWG exports. Introduced in v1.x." }, "include_xdata": { "type": "boolean", "default": false, "description": "Whether to include extended data (XData) in this layer for DWG exports. Introduced in v1.x." } }, "required": [ "item" ] }, "ExportDatasetItemList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/ExportDatasetItem" }, "description": "A list of layer, table or dataset items to export." }, "ExportCreateRequest": { "type": "object", "properties": { "crs": { "type": "string", "description": "The coordinate reference system in the form EPSG:XXXX where XXXX is the identifier. For more info on EPSG, refer to http://epsg.io. Please note that KML exports can only be exported in WGS84 / EPSG:4326.", "example": "EPSG:26767" }, "formats": { "type": "object", "description": "An object keyed by layer or table \"kind\" (see Layers & tables API kind property) with the mimetype of the format you want in the download. You must have one entry for each data kind you are exporting.", "example": { "raster": "application/x-hdf;subtype=kea", "vector": "applicaton/x-ogc-filegdb" } }, "items": { "$ref": "#/components/schemas/ExportDatasetItemList" }, "name": { "type": "string", "description": "The name for the archive. If not provided this will be generated from the content." }, "extent": { "type": "string", "description": "A Crop Feature or Geometry extent for cropping to a specific geographic area." }, "options": { "type": "object", "description": "Additional format options" }, "delivery": { "type": "object", "description": "Delivery details (omit this when creating a downloadable export)", "properties": { "method": { "type": "string", "description": "The delivery method", "enum": [ "download" ] } } } }, "required": [ "crs", "formats", "items" ] }, "ExportFormOptionBase": { "type": "object", "properties": { "required": { "type": "boolean" }, "read_only": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "type" ] }, "ExportFormOptionPrimitive": { "allOf": [ { "$ref": "#/components/schemas/ExportFormOptionBase" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "integer", "datetime", "field", "boolean" ] } } } ] }, "ExportFormOptionChoice": { "allOf": [ { "$ref": "#/components/schemas/ExportFormOptionBase" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "choices": { "type": "array", "items": { "type": "object", "properties": { "display_name": { "type": "string" }, "value": { "type": "string" } } } } } } ] }, "ExportFormOptionNested": { "allOf": [ { "$ref": "#/components/schemas/ExportFormOptionBase" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "nested object" ] }, "children": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, { "$ref": "#/components/schemas/ExportFormOptionChoice" } ], "discriminator": { "propertyName": "type" } } } } } ] }, "ExportFormOptionList": { "allOf": [ { "$ref": "#/components/schemas/ExportFormOptionBase" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "child": { "$ref": "#/components/schemas/ExportFormOptionNested" } } } ] }, "ExportFilters": { "type": "object", "properties": { "created_via": { "type": "string", "example": "web", "enum": [ "", "web", "api", "app" ] }, "state": { "type": "string", "example": "complete", "enum": [ "processing", "cancelled", "error", "complete", "gone" ] }, "user": { "type": "number", "example": 5, "description": "User ID" }, "created_at": { "type": "string", "format": "date-time", "example": "2000-01-01 01:01:01.000000" }, "delivery_method": { "type": "string", "example": "download", "enum": [ "download", "courier" ] } } }, "ExportOptionsResponse": { "type": "object", "properties": { "actions": { "type": "object", "properties": { "POST": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "name": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "created_at": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "created_via": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "state": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "url": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "download:url": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "extent": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "delivery": { "$ref": "#/components/schemas/ExportFormOptionNested" }, "formats": { "$ref": "#/components/schemas/ExportFormOptionNested" }, "items": { "$ref": "#/components/schemas/ExportFormOptionList" }, "crs": { "$ref": "#/components/schemas/ExportFormOptionPrimitive" }, "options": { "$ref": "#/components/schemas/ExportFormOptionNested" }, "expansions": { "type": "array", "items": { "type": "string" } }, "filters": { "$ref": "#/components/schemas/ExportFilters" } } } } } } }, "CoordinateSystemListItem": { "type": "object", "properties": { "id": { "type": "string", "example": "EPSG:4326" }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/coordinate-systems/EPSG:4326/" }, "name": { "type": "string", "example": "WGS 84" }, "kind": { "$ref": "#/components/schemas/CoordinateSystemKind" }, "unit_horizontal": { "type": "string", "example": "degree", "nullable": true, "description": "Null for vertical coordinate systems" }, "unit_vertical": { "type": "string", "example": null, "nullable": true, "description": "Non-null for vertical and compound coordinate systems; null otherwise" }, "url_external": { "type": "string", "format": "url", "example": "https://epsg.io/4326" }, "srid": { "type": "integer", "example": 4326, "nullable": true, "deprecated": true, "description": "Integer identifier for EPSG coordinate systems only. Use `id` instead" } } }, "ExportItemValidationResult": { "type": "object", "properties": { "invalid_reasons": { "type": "array", "items": { "type": "string", "enum": [ "over-size-limit:max-{overall-size-limit}", "missing-crs", "kml-invalid-crs", "no-layers", "over-size-limit:${mime-type}:max-{format-size-limit}" ] } }, "is_valid": { "type": "boolean" }, "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ExportDatasetItem" }, { "type": "object", "properties": { "is_valid": { "type": "boolean" }, "size_estimate_zipped": { "type": "number", "description": "Value in bytes" }, "invalid_reasons": { "type": "array", "items": { "type": "string", "enum": [ "over-size-limit:${mime-type}:max-{format-size-limit}" ] } } } } ] } }, "name": { "type": "string", "example": "local-anomalies" }, "size_estimate_zipped": { "type": "number", "example": 386247930323, "description": "Value in bytes" }, "suggested_crs": { "type": "array", "items": { "$ref": "#/components/schemas/CoordinateSystemListItem" } }, "suggested_crs_vertical": { "type": "array", "items": { "$ref": "#/components/schemas/CoordinateSystemListItem" } } } }, "ApiErrorResponse": { "type": "object", "properties": { "status_code": { "type": "number", "enum": [ 400 ] }, "errors": { "type": "object" } } }, "CropFeature": { "type": "object", "properties": { "id": { "type": "integer", "example": 3456 }, "name": { "type": "string", "description": "The value of the crop layer's `label_attribute` for this feature.", "example": "Wellington City" }, "url": { "type": "string", "format": "url", "description": "Pass this as an export's `extent` to crop to this feature.", "example": "https://data.example.com/services/api/v1.x/exports/croplayers/12/cropfeatures/3456/" } } }, "CropLayer": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "description": "The title of the source layer's published version. Read-only; rename the source layer to change it.\n", "example": "NZ Territorial Authorities" }, "url": { "type": "string", "format": "url", "example": "https://data.example.com/services/api/v1.x/exports/croplayers/12/" }, "features": { "description": "URL of the crop feature list, or the inlined list when the `Expand: features` header is used. The inlined list may include obsolete features after regeneration; follow the URL for current features.\n", "oneOf": [ { "type": "string", "format": "url", "example": "https://data.example.com/services/api/v1.x/exports/croplayers/12/cropfeatures/" }, { "type": "array", "items": { "$ref": "#/components/schemas/CropFeature" } } ] }, "extent": { "description": "The extent of the source layer.", "allOf": [ { "$ref": "#/components/schemas/MultiPolygon" } ] }, "source_layer": { "type": "string", "format": "url", "description": "The source layer's currently published version.", "example": "https://data.example.com/services/api/v1.x/layers/1234/versions/5678/" } } }, "CropLayerList": { "type": "array", "items": { "$ref": "#/components/schemas/CropLayer" } }, "CropLayerCreateRequest": { "type": "object", "required": [ "source_layer", "label_attribute" ], "properties": { "source_layer": { "type": "string", "format": "url", "description": "URL of the layer to build crop features from. Must be a published vector polygon layer with at most 1000 features, visible to the authenticated user.\n", "example": "https://data.example.com/services/api/v1.x/layers/1234/" }, "label_attribute": { "type": "string", "maxLength": 255, "description": "Name of a string field of the layer. Each crop feature is named by this field's value.\n", "example": "name" } } }, "CropFeatureList": { "type": "array", "items": { "$ref": "#/components/schemas/CropFeature" } }, "CropFeatureDetail": { "allOf": [ { "$ref": "#/components/schemas/CropFeature" }, { "type": "object", "properties": { "geometry": { "description": "The simplified geometry, in EPSG:4326. Cropping uses the full geometry, so an export's extent is not limited to this.\n", "allOf": [ { "$ref": "#/components/schemas/MultiPolygon" } ] } } } ] }, "Notification": { "type": "object", "description": "A notification, as carried in an SSE `data:` line or a long-poll response body.", "required": [ "channel", "event", "data" ], "properties": { "channel": { "type": "string", "description": "Which stream of notifications this belongs to.", "enum": [ "publishing", "scans", "exports", "mapviewers" ], "example": "publishing" }, "event": { "type": "string", "description": "What happened. The set of events depends on the channel.", "example": "publish-finished" }, "data": { "type": "object", "description": "Event-specific payload; see the channel table on the SSE endpoint.", "example": { "id": 42, "state": "completed", "url": "https://{domain}/services/api/v1.x/publish/42/" } } } }, "ThemeSerializer": { "type": "object", "properties": { "background_color": { "type": "string", "description": "Hex color" }, "secondary_color": { "type": "string", "description": "Hex color" }, "primary_text_color": { "type": "string", "description": "Hex color" }, "primary_color": { "type": "string", "description": "Hex color" }, "logo": { "type": "string" }, "secondary_logo": { "type": "string" }, "favicon": { "type": "string" } } }, "UserMenuItems": { "type": "object", "properties": { "type": { "description": "Item type. If link, title and URL fields are mandatory.", "type": "string", "enum": [ "link", "divider" ] }, "title": { "type": "string" }, "url": { "type": "string", "format": "url" } }, "required": [ "type" ] }, "UserMenus": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserMenuItems" } } }, "required": [ "title", "items" ] }, "HelpMenuItems": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "url" } }, "required": [ "title", "url" ] }, "TileGridSerializer": { "type": "object", "properties": { "id": { "type": "integer" }, "srd": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string", "format": "url" } } }, "GeoTagWithExtentSerializer": { "type": "object", "properties": { "country_code": { "type": "string" }, "state_code": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" }, "extent": { "type": "object", "description": "Geometry representing the spatial extent" } } }, "SiteSerializer": { "type": "object", "properties": { "name": { "type": "string" }, "owner": { "type": "string" }, "owner_short": { "type": "string" }, "domain": { "type": "string", "example": "example.koordinates.com" }, "copyright": { "type": "string" }, "ui_version": { "type": "string" }, "theme": { "type": "object", "$ref": "#/components/schemas/ThemeSerializer" }, "user_menus": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/UserMenus" } }, "help_menus": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/HelpMenuItems" } }, "hs_property_id": { "type": "string", "description": "HubSpot ID" }, "ecommerce": { "type": "boolean", "description": "Whether e-commerce is enabled for this site" }, "flags": { "type": "object" }, "geocoder": { "type": "object" }, "basemap": { "type": "object" }, "sentry_dsn": { "type": "string" }, "org_url": { "type": "string", "format": "url" }, "tile_cdn_urls": { "type": "string" }, "tilegrids": { "type": "array", "description": "**Expandable**\n", "items": { "oneOf": [ { "type": "string", "format": "url", "description": "URL of tilegrid." }, { "type": "object", "description": "*Expansion*: a TileGrid object\n", "$ref": "#/components/schemas/TileGridSerializer" } ] } }, "geotag": { "type": "object", "$ref": "#/components/schemas/GeoTagWithExtentSerializer" } } }, "SiteAccessRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "declined", "expired" ] }, "url": { "type": "string", "format": "url" }, "id": { "type": "integer" }, "created_by": { "type": "object", "$ref": "#/components/schemas/RelatedUserSerializer" }, "updated_by": { "type": "object", "$ref": "#/components/schemas/RelatedUserSerializer" }, "user": { "type": "object", "$ref": "#/components/schemas/RelatedUserSerializer" }, "created_at": { "type": "string", "example": "2020-05-16T23:37:45.632286Z" }, "updated_at": { "type": "string", "example": "2020-05-16T23:37:45.632286Z" } } }, "SiteAccessRequestList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/SiteAccessRequest" } }, "SiteAccessRequestCreate": { "type": "object", "properties": { "user_id": { "type": "number", "description": "ID of the user the request is tied to" } }, "required": [ "user_id" ] }, "UserMenuListAndCreateResponse": { "type": "object", "properties": { "user_menus": { "type": "array", "minimum": 0, "maximum": 2, "items": { "$ref": "#/components/schemas/UserMenus" } } } }, "UserMenuCreateRequest": { "description": "A custom user menu creation payload", "type": "object", "properties": { "user_menus": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Item Type [link | divider]" }, "title": { "type": "string", "description": "Item title if link" }, "url": { "type": "string", "format": "url", "description": "Item url if link" } }, "required": [ "type" ] } } } } } }, "HelpMenuListAndCreateResponse": { "type": "object", "properties": { "help_menus": { "type": "array", "minimum": 0, "maximum": 5, "items": { "$ref": "#/components/schemas/HelpMenuItems" } } } }, "HelpMenuCreateRequest": { "description": "A custom help menu creation payload", "type": "object", "properties": { "help_menus": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "url" } }, "required": [ "title", "url" ] } } } }, "ExternalServiceTemplate": { "type": "object", "description": "A reusable definition for an external (third-party) service. Once a template exists, external services can be attached to layers and tables from it. See the [Services documentation](#tag/Services).\n", "properties": { "id": { "type": "integer", "readOnly": true }, "title": { "type": "string", "maxLength": 80, "description": "Display title for the template." }, "short_name": { "type": "string", "maxLength": 25, "description": "Short name, usable in the `{shortname}` URL token." }, "description": { "type": "string", "maxLength": 500 }, "template_urls": { "type": "array", "minItems": 1, "maxItems": 3, "description": "The service URLs to expose. Within a `service_url`, the tokens `{id}`, `{shortname}` and `{title}` are substituted, when a service is attached, with the target dataset's ID, short name and title respectively (these refer to the dataset, not the template's own `short_name`). Any other text — including tile placeholders such as `{z}/{x}/{y}` — is left unchanged.\n", "items": { "type": "object", "properties": { "name": { "type": "string" }, "service_url": { "type": "string", "example": "https://example.com/wms/{id}?" } }, "required": [ "service_url" ] } }, "scope": { "type": "array", "minItems": 1, "description": "Which dataset types the template can be attached to. List one or more of: `all` (matches every dataset, including any layer — use this for a generic basemap or service not tied to the dataset's data); `layer` (any non-table layer, i.e. vector, raster or grid); `vector`, `raster` or `grid` (layers of that specific data type); `table` (tables). At attach time the target dataset must match at least one listed value, or the attach is rejected. Non-layer datasets (such as sets and catalog items) match only `all`.\n", "items": { "type": "string", "enum": [ "all", "layer", "vector", "raster", "grid", "table" ] } }, "enabled": { "type": "boolean", "description": "Whether the template is enabled. This does not block attaching and does not change the state of services attached from it — a service's enabled state is set by the `enabled` field of the attach request. To take a template out of service, set `suspended`.\n" }, "access_policy": { "type": "string", "default": "all-users", "description": "Which users may consume services created from this template. Defaults to `all-users`. One of: `disabled` (no one); `all-users` (anyone with access to the dataset); `paid-seats` (users with a paid seat); `paid-seats-and-third-party-auth` (paid seats plus third-party-authenticated users); `koordinates-staff` (Koordinates staff only).\n", "enum": [ "disabled", "all-users", "paid-seats", "paid-seats-and-third-party-auth", "koordinates-staff" ] }, "suspended": { "type": "boolean", "description": "Whether the template is suspended. Suspended templates cannot be attached to new datasets. A template cannot be created suspended.\n" }, "used_by": { "type": "integer", "readOnly": true, "description": "Number of external services currently using this template." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "ExternalServiceTemplateList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/ExternalServiceTemplate" } }, "ExternalServiceTemplateWriteRequest": { "type": "object", "description": "Fields for creating or updating an external service template. A template cannot be created in a suspended state, so `suspended` may only be set to `true` when updating; on create, `suspended` must be `false` (or omitted).\n", "properties": { "title": { "type": "string", "maxLength": 80 }, "short_name": { "type": "string", "maxLength": 25 }, "description": { "type": "string", "maxLength": 500 }, "template_urls": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "properties": { "name": { "type": "string" }, "service_url": { "type": "string", "example": "https://example.com/wms/{id}?" } }, "required": [ "service_url" ] } }, "scope": { "type": "array", "minItems": 1, "description": "Which dataset types the template can be attached to. List one or more of: `all` (any dataset); `layer` (any non-table layer, i.e. vector, raster or grid); `vector`, `raster` or `grid` (layers of that specific data type); `table` (tables). Only `all` matches non-layer datasets.\n", "items": { "type": "string", "enum": [ "all", "layer", "vector", "raster", "grid", "table" ] } }, "enabled": { "type": "boolean", "description": "Whether the template itself is enabled." }, "access_policy": { "type": "string", "description": "Which users may consume services created from this template. Defaults to `all-users`. One of: `disabled` (no one); `all-users` (anyone with access to the dataset); `paid-seats` (users with a paid seat); `paid-seats-and-third-party-auth` (paid seats plus third-party-authenticated users); `koordinates-staff` (Koordinates staff only).\n", "enum": [ "disabled", "all-users", "paid-seats", "paid-seats-and-third-party-auth", "koordinates-staff" ] }, "suspended": { "type": "boolean" } }, "required": [ "title", "short_name", "template_urls", "scope" ] }, "ServiceTemplateSerializer": { "type": "object", "properties": { "name": { "type": "string" }, "service_url": { "type": "string", "format": "url" } } }, "ServiceSerializer": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the service.\n" }, "key": { "type": "string", "description": "The service type key (for example `wfs`, `tiles`, `export`). See the [Services documentation](#tag/Services) for the full list of service types. Writable on creation; read-only thereafter. The `*-ui` keys are internal UI-visibility controls.\n", "example": "wfs", "enum": [ "kart", "csw", "spatial-query-grid", "spatial-query-tiles", "spatial-query-vector", "spatial-query-set", "data-table", "wfs", "wfs-changesets", "tiles", "esri-map", "wmts", "vector-tile-pmtiles", "vector-tile-mvt", "vector-tile-mbtiles", "vector-tile-arcgis", "vector-tile-json", "raster-pmtile", "raster-tile-json", "copc", "esri-rest-api", "3d-tiles", "ifc", "kart-diff", "export", "small-data", "external", "kart-ui", "spatial-query-ui", "data-table-ui", "vector-tile-pmtiles-ui", "copc-ui" ] }, "authority": { "type": "string", "description": "A reference to the authority that specifies the service, for example, \"OGC\"\n" }, "short_name": { "type": "string", "description": "The short name for the service.\n" }, "label": { "type": "string", "description": "Longer descripion of the service\n" }, "auth_method": { "type": "array", "description": "Enumerates the valid authentication methods for this service, if available.\n", "items": { "type": "string", "enum": [ "apikey" ] } }, "auth_scopes": { "type": "array", "description": "Enumerates the valid scopes for this service, if available for Koordinates APIs.\n", "items": { "type": "string" } }, "domain": { "type": "string", "description": "The domain of the service.\n" }, "enabled": { "type": "boolean", "description": "Whether the service is enabled. Cannot be set to false for ad-hoc services, or for service types that do not enforce permissions.\n" }, "advertised": { "type": "boolean", "description": "Whether the service is advertised to users.\n" }, "permissions": { "type": "string", "format": "url", "description": "URL to to the permissions management endpoints for this service. Can be expanded with the `Expand` header to inline the permission list.\n" }, "template_urls": { "type": "array", "description": "Lists the URLs for accessing this service, if applicable.\n", "minimum": 0, "items": { "$ref": "#/components/schemas/ServiceTemplateSerializer" } }, "capabilities": { "type": "array", "description": "Capabilities provided by this service.\n", "items": { "type": "string" } }, "user_capabilities": { "type": "array", "description": "Capabilities available to the requesting user for this service.\n", "items": { "type": "string" } }, "tilegrids": { "type": "array", "description": "WMTS only (`key: tiles`): available tile grids. Omitted for other service types.\n", "items": { "type": "object" } }, "styles": { "type": "array", "description": "WMTS only (`key: tiles`): available styles. Omitted for other service types.\n", "items": { "type": "object" } }, "kind": { "type": "string", "example": "external", "description": "Present only for external services. Value is `external`.\n" }, "description": { "type": "string", "description": "Present only for external services.\n" }, "mime_type": { "type": "string", "description": "Present only for small-data services (`key: small-data`): the MIME type of the served data.\n" } } }, "ServicesList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/ServiceSerializer" } }, "ServiceUpdateRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "ServicePermission": { "type": "object", "properties": { "group": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "example": 999, "description": "Either \"everyone\", \"registered-users\", or an integer representing a Group ID\n" }, "permission": { "type": "string", "enum": [ "access" ], "example": "access" } } }, "ServicePermissionList": { "type": "array", "items": { "$ref": "#/components/schemas/ServicePermission" } }, "ServicePermissionCreateRequest": { "type": "object", "description": "Supply exactly one owner: either `group` or `user`.\n", "properties": { "group": { "type": "integer", "description": "ID of the group to grant access to. Mutually exclusive with `user`." }, "user": { "type": "integer", "description": "ID of the user to grant access to. Mutually exclusive with `group`." }, "permission": { "type": "string", "enum": [ "access" ] } }, "required": [ "permission" ] }, "ServicePermissionListReplaceRequest": { "type": "array", "description": "The full set of service permissions, supplied as a top-level array. Replaces any existing permissions on the service.\n", "items": { "$ref": "#/components/schemas/ServicePermissionCreateRequest" } }, "ExternalServiceAttachRequest": { "type": "object", "description": "Attach an external service to a layer or table from a template.", "properties": { "template_id": { "type": "integer", "description": "ID of an active (non-suspended) external service template. Its `scope` must match this dataset's type.\n" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the attached service is enabled. This alone controls the new service's state, regardless of the template's own `enabled` value.\n" } }, "required": [ "template_id" ] }, "ExternalServiceUpdateRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "CategoryItemSerializer": { "type": "object", "properties": { "name": { "type": "string", "example": "Category 3" }, "slug": { "type": "string", "example": "category-3" }, "key": { "type": "string", "example": "category-1/category-2/category-3" }, "url": { "type": "string", "format": "url", "example": "https://testserver.com/services/api/v1.x/categories/category-1/category-2/category-3/" }, "children": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/CategoryItemSerializer" } } } }, "CategoryList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/CategoryItemSerializer" } }, "CreateCategoryRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "Category 1" }, "slug": { "type": "string", "description": "A URL-friendly name for the category. Will be generated automatically if not provided.\nMust be unique within the current set of children.\n" }, "parent": { "type": "string", "format": "url", "description": "The URL of the parent category." } }, "required": [ "name" ] }, "CreateCategoryResponse": { "type": "object", "description": "The category as returned when creating one via POST. Unlike the read response, this includes the `parent` reference and does not nest `children`.\n", "properties": { "name": { "type": "string", "example": "Category 3" }, "slug": { "type": "string", "example": "category-3" }, "key": { "type": "string", "example": "category-1/category-2/category-3" }, "url": { "type": "string", "format": "uri", "example": "https://testserver.com/services/api/v1.x/categories/category-1/category-2/category-3/" }, "parent": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the parent category, or null for a top-level category.", "example": "https://testserver.com/services/api/v1.x/categories/category-1/category-2/" } } }, "UpdateCategoryRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "Category 1" }, "slug": { "type": "string", "description": "A URL-friendly name for the category. Will be generated automatically if not provided.\nMust be unique within the current set of children.\n" }, "parent": { "type": "string", "format": "url", "description": "The URL of the parent category." } } }, "Token": { "type": "object", "properties": { "id": { "type": "integer", "example": 531 }, "name": { "type": "string", "example": "Example Token" }, "key_hint": { "type": "string", "example": "0035ee..." }, "url": { "type": "string", "format": "uri" }, "site": { "type": "string", "example": "example.koordinates.com" } } }, "TokenList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/Token" } }, "DetailedToken": { "allOf": [ { "$ref": "#/components/schemas/Token" }, { "type": "object", "properties": { "scope": { "type": "string", "example": "layers:read documents:read" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the token stops working. ```null``` means it never expires.\nA token past this time is omitted from the token list unless ```include_expired=true```, but it can be revived by ```PUT```ting a new future value here.\n" }, "suspended_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "description": "When the token was suspended, or ```null``` if it isn't suspended. Set only by the suspend/resume endpoints; sending it here is ignored.\n" }, "last_used_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true, "description": "The last day this token was used to authenticate, or ```null``` if it hasn't been used since we started recording this.\nDay granularity, and a lower bound: tile and other service traffic is validated behind a short-lived cache, so some uses are not individually recorded.\n" }, "referrers": { "type": "array", "items": { "type": "string" }, "example": [ "https://example.com" ] }, "groups_scope": { "type": "array", "items": { "type": "string" }, "example": [ "g.108.owned", "g.108.access" ], "description": "Restricts API key to a group. Follows the format of `g..`. Where group-id is the ID of the group and permission is the permission granted to the token. Permissions can be:\n - `owned` - Limit to datasets owned by the group\n - `access` - Limit to datasets accessible to a group (including owned datasets)\n\nThe `access` scope implies an `owned` scope, and thus cannot exist without an `owned` counterpart. The `owned` scope can exist without an `access` scope. If no `groups_scope` is provided, the token has no group restrictions.\n" } } } ] }, "DetailedTokenWithKey": { "allOf": [ { "$ref": "#/components/schemas/DetailedToken" }, { "type": "object", "properties": { "key": { "type": "string", "example": "0035ee0000000000000000000000" } } } ] }, "DataList": { "type": "array", "minimum": 0, "description": "A mixed list of catalog items. Each entry is the summary representation of its type, as returned by that type's own list endpoint: layers and tables (see `Layers`), catalog items (`CatalogItemSerializer`), Kart repositories (`RepoItemSerializer`) and Kart datasets (`RepoDataset`), plus sets, documents, map viewers and sources, which have no standalone schema here.\n", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The item type: `layer`, `table`, `set`, `document`, `repo`, `map` or `catalog-item`. Sources report their source type.\n", "example": "layer" } }, "additionalProperties": true } }, "LayersTablesPostPermissionsSerializer": { "type": "array", "items": { "type": "string" }, "example": [ "find", "view", "download" ] }, "Layers": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "url": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/" }, "type": { "type": "string", "example": "layer" }, "title": { "type": "string", "example": "Fictional Boundary Points" }, "first_published_at": { "type": "string", "format": "date-time", "example": "2013-12-03T03:56:55Z" }, "thumbnail_url": { "type": "string", "format": "uri", "example": "https://tiles.{domain}/services/tiles/v4/thumbnail/layer=1.1,style=auto/1200x630.png" }, "published_at": { "type": "string", "format": "date-time", "example": "2013-12-03T03:56:55Z" }, "featured_at": { "type": "string", "format": "date-time", "example": null }, "services": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/services/" }, "user_permissions": { "$ref": "#/components/schemas/LayersTablesPostPermissionsSerializer" }, "public_access": { "type": "string", "example": "download" } } }, "LayersTables": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/Layers" } }, "LayersLicenseSerializer": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "title": { "type": "string", "example": "Creative Commons Attribution 3.0 New Zealand" }, "type": { "type": "integer", "example": 1 }, "type_name": { "type": "string", "example": "Creative Commons license" }, "url": { "type": "string", "format": "url", "example": "https://data-test.linz.govt.nz/services/api/v1/licenses/3/" } } }, "PermissionArray": { "minimum": 0, "type": "array", "items": { "type": "object", "properties": { "group": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "example": 999, "description": "Either \"everyone\", \"registered-users\", or an integer representing a Group ID\n" }, "permission": { "type": "string", "enum": [ "find", "view", "manage_data", "admin" ], "example": "view" } } } }, "LayersAutoupdateSerializer": { "type": "object", "properties": { "behavior": { "type": "string", "example": "yes-noschema", "default": "no", "enum": [ "no", "yes-noschema", "yes-always" ], "description": "Controls the auto-update behavior for the layer.\n- \"no\": Auto-update is disabled for this layer.\n- yes-noschema: Auto-update is enabled whenever new data is available, but only if the schema remains unchanged.\n- yes-always: Auto-update is always enabled.\n" }, "schedule": { "type": "string", "example": "0 0 0,4 * *", "description": "A 'cron expression' comprising 5 fields separated by whitespace (note: minutes are ignored),\nor one of the strings '@hourly', '@daily', @weekly', '@monthly', '@yearly'\n" } } }, "LayersDataSerializer": { "type": "object", "properties": { "datasources": { "type": "object", "properties": { "id": { "type": "integer", "example": 345 } } }, "encoding": { "type": "string", "example": "utf-8" }, "crs": { "type": "string", "example": "EPSG:4326" }, "elevation_field": { "type": "string", "example": "Z" }, "primary_key_field": { "type": "string", "example": "id" }, "geometry_field": { "type": "array", "items": {}, "example": "GEOMETRY, WKT, [X, Y], null" } }, "required": [ "datasources" ] }, "LayersTablesPostRequest": { "type": "object", "properties": { "title": { "type": "string", "example": "Fictional Boundary Points" }, "description": { "type": "string", "example": "These points are totally fictional!" }, "collected": { "type": "string", "format": "date", "example": "2013-01-01" }, "license": { "$ref": "#/components/schemas/LayersLicenseSerializer" }, "supplier_reference": { "type": "string", "example": "TIVPAS" }, "version_reference": { "type": "string", "example": "added more data" }, "default_style_id": { "type": "integer", "example": 3 }, "publish": { "type": "boolean", "example": true }, "mapstream_id": { "type": "integer", "example": 3 }, "categories": { "type": "string", "example": "topographic/nz-topo-offshore-islands-data/terrain" }, "tags": { "type": "array", "example": "tag2, tag2" }, "permissions": { "$ref": "#/components/schemas/PermissionArray" }, "publish_to_catalog_services": { "type": "boolean", "example": true }, "autoupdate": { "$ref": "#/components/schemas/LayersAutoupdateSerializer" }, "data": { "$ref": "#/components/schemas/LayersDataSerializer" }, "tilegrids": { "type": "array", "example": "[]" } }, "required": [ "title", "data" ] }, "LayersTablesPostUserSerializer": { "type": "object", "properties": { "id": { "type": "number", "example": 3 }, "url": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/users/3/" }, "first_name": { "type": "string", "example": "Bob" }, "last_name": { "type": "string", "example": "Jones" }, "country": { "type": "string", "example": "NY" } } }, "LayersTablesPostGroupSerializer": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "A group" } } }, "LayersTablesPostExtentSerializer": { "type": "object", "properties": { "type": { "type": "string", "example": "Polygon" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number", "example": "167.59282355089192, -45.03245508994864" } } } } } }, "LayersTablesPostFieldsSerializer": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "GEOMETRY" }, "type": { "type": "string", "example": "geometry" } } } }, "LayersTablesPostLogSerializer": { "type": "object", "properties": { "invalid_geometries": { "type": "integer", "example": 0 }, "messages": { "type": "integer", "example": 0 } } }, "LayersTablesPostChangeSerializer": { "type": "object", "properties": { "deleted": { "type": "integer", "example": 0 }, "updated": { "type": "integer", "example": 0 }, "inserted": { "type": "integer", "example": 2 }, "schema_changes": { "type": "object", "properties": { "added": { "type": "array", "example": [] }, "change": { "type": "array", "example": [] }, "geometry_type_changed": { "type": "boolean", "example": false }, "primary_keys_changed": { "type": "boolean", "example": false }, "srid_changed": { "type": "boolean", "example": false } } } } }, "LayersTablesPostFormatsSerializer": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Shapefile" }, "mimetype": { "type": "string", "example": "application/x-zipped-shp" } } } }, "LayersTablesPostDataSerializer": { "type": "object", "properties": { "storage": { "type": "string", "example": "Classic" }, "encoding": { "type": "string", "example": "none" }, "extent": { "$ref": "#/components/schemas/LayersTablesPostExtentSerializer" }, "crs": { "type": "string", "example": "EPSG:4326" }, "crs_display": { "type": "string", "example": "WGS 84" }, "primary_key_fields": { "type": "string", "example": "GEOMETRY" }, "datasources": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/datasources/" }, "datasource_count": { "type": "integer", "example": 1 }, "geometry_field": { "type": "string", "example": "GEOMETRY" }, "geometry_type": { "type": "string", "example": "point" }, "tile_revision": { "type": "number", "example": 1 }, "fields": { "$ref": "#/components/schemas/LayersTablesPostFieldsSerializer" }, "feature_count": { "type": "integer", "example": 200 }, "import_started_at": { "type": "string", "format": "date-time", "example": "2013-12-03T15:00:27.870364Z" }, "import_ended_at": { "type": "string", "format": "date-time", "example": "2013-12-03T15:00:27.870364Z" }, "import_log": { "$ref": "#/components/schemas/LayersTablesPostLogSerializer" }, "change_summary": { "$ref": "#/components/schemas/LayersTablesPostChangeSerializer" }, "source_summary": { "type": "object", "properties": { "paths": { "type": "string", "example": "fictional_points.shp" }, "filenames": { "type": "string", "example": "fictional_points.zip" }, "descriptions": { "type": "string", "example": "Example description" }, "types": { "type": "string", "example": "Upload" }, "formats": { "type": "string", "example": "Shapefile" } } }, "import_version": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/" }, "update_available": { "type": "boolean", "example": false }, "sample": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/data/sample/" }, "raster_resolution": { "type": "string", "example": null }, "empty_geometry_count": { "type": "number", "example": 0 }, "has_z": { "type": "boolean", "example": false }, "export_formats": { "$ref": "#/components/schemas/LayersTablesPostFormatsSerializer" } } }, "LayerDetail": { "type": "object", "properties": { "title": { "type": "string", "example": "Fictional Boundary Points" }, "id": { "type": "integer", "example": 123 }, "url": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/" }, "type": { "type": "string", "example": "layer" }, "collected_at": { "type": "string", "format": "date", "example": [ "2013-01-01" ] }, "created at": { "type": "string", "format": "date", "example": [ "2013-01-01" ] }, "first_published_at": { "type": "string", "format": "date", "example": [ "2013-01-01" ] }, "thumbnail_url": { "type": "string", "format": "uri", "example": "https://tiles.{domain}/services/tiles/v4/thumbnail/layer=1.1,style=auto/1200x630.png" }, "services": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/services/", "description": "URL to the services configured for this layer. See the [Services documentation](#tag/Services) for how to list, enable/disable and set permissions on services.\n" }, "user_permissions": { "$ref": "#/components/schemas/LayersTablesPostPermissionsSerializer" }, "user": { "$ref": "#/components/schemas/LayersTablesPostUserSerializer" }, "description": { "type": "string", "example": "These points are totally fictional!" }, "description_html\"": { "type": "string", "example": "

These points are totally fictional!

" }, "group": { "$ref": "#/components/schemas/LayersTablesPostGroupSerializer" }, "data": { "$ref": "#/components/schemas/LayersTablesPostDataSerializer" }, "url_html": { "type": "string", "format": "uri", "example": "https://koordinates.com/layer/123-fictional-points/" }, "published_version": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/" }, "latest_version": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/" }, "this_version": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/" }, "kind": { "type": "string", "example": "vector" }, "categories": { "type": "array", "example": [] }, "tags": { "type": "array", "example": [] }, "license": { "type": "string", "example": null }, "metadata": { "type": "string", "example": null }, "elevation_field": { "type": "string", "example": "" }, "publish_to_catalog_services": { "type": "boolean", "example": "https://{domain}/services/api/v1/layers/123/permissions/" }, "autoupdate": { "$ref": "#/components/schemas/LayersAutoupdateSerializer" }, "supplier_reference": { "type": "string", "example": " " }, "styles": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/styles/" }, "attachments": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/attachments/" }, "tilegrids": { "type": "array", "example": [] }, "num_views": { "type": "number", "example": 1050 }, "num_downloads": { "type": "number", "example": 0 }, "repository": { "type": "object", "example": {} }, "geotags": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/versions/456/geotags/" }, "public_access": { "type": "string", "example": "download" }, "settings": { "type": "object", "example": {} }, "default_style": { "type": "string", "example": null } } }, "LayersTablesDraft": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "url": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/" }, "type": { "type": "string", "example": "layer" }, "first_published_at": { "type": "string", "format": "date-time", "example": "2013-01-01T00:01:01" }, "published_at": { "type": "string", "format": "date-time", "example": "2013-12-03T03:56:55Z" } } }, "LayerOwnerRequest": { "type": "object", "description": "Change the owner of a layer or table. Supply exactly one of `user` or\n`group`. The change takes effect immediately and is independent of the\npublishing workflow.\n", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 } } }, "group": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 } } } } }, "LayersTablesVersionInfo": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "url": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/1/versions/7/" }, "created_at": { "type": "string", "format": "date-time", "example": [ "2013-03-01 00:00:01" ] }, "reference": { "type": "string", "example": "More data" }, "data_import": { "type": "boolean", "example": false }, "status": { "type": "string", "example": "importing" }, "progress": { "type": "number", "example": 0.5, "description": "Approximate fraction (0-1) of the import and tile build completed so far. Not a time estimate; it may plateau for long periods." } } }, "LayersTablesVersionList": { "type": "array", "items": { "$ref": "#/components/schemas/LayersTablesVersionInfo" } }, "LayersTablesPostDraft": { "type": "object", "properties": { "title": { "type": "string", "example": "Fictional Boundary Points" }, "description": { "type": "string", "example": "These points are totally fictional!" }, "collected": { "type": "string", "format": "date", "example": [ "2013-01-01" ] }, "license": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "title": { "type": "string", "example": "Creative Commons Attribution 3.0 New Zealand" }, "type": { "type": "integer", "example": 1 }, "type_name": { "type": "string", "example": "Creative Commons license" }, "url": { "type": "string", "format": "uri", "example": "https://data-test.linz.govt.nz/services/api/v1/licenses/3/" } } }, "supplier_reference": { "type": "string", "example": "TIVPAS" }, "version_reference": { "type": "string", "example": "added more data" }, "default_style_id": { "type": "integer", "example": 3 }, "publish": { "type": "boolean", "example": true }, "categoties": { "type": "string", "format": "uri", "example": [ "topographic/nz-topo-offshore-islands-data/terrain" ] }, "tags": { "type": "array", "items": { "type": "string", "example": [ "tag1", "tag2" ] } }, "permissions": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/layers/123/permissions/" }, "publish_to_catalog_services": { "type": "boolean", "example": true }, "autoupdate": { "$ref": "#/components/schemas/LayersAutoupdateSerializer" }, "data": { "$ref": "#/components/schemas/LayersDataSerializer" }, "tilegrids": { "type": "string", "example": "EPSG:2193" }, "default_style": { "type": "integer", "example": 10 } } }, "DatasourceGeotag": { "type": "object", "properties": { "country_code": { "type": "string", "nullable": true, "example": "NZ" }, "state_code": { "type": "string", "nullable": true, "example": null }, "name": { "type": "string", "example": "New Zealand" }, "key": { "type": "string", "description": "The geotag URL, as accepted by the `geotag` filter.", "example": "global/oceania/new-zealand" } } }, "DatasourceDetail": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "format": "url", "example": "https://koordinates.com/services/api/v1/sources/36/datasources/1/" }, "title": { "type": "string", "description": "The datasource's title. Falls back to a name derived from the file name (or the layer name within a multi-layer file) when the source data provides no title.", "example": "Null Island Polygons" }, "data_type": { "type": "string", "example": "vector" }, "geometry_type": { "type": "string", "example": "polygon" }, "updated_at": { "type": "string", "example": "2012-11-14T02:53:46Z" }, "state": { "type": "string", "enum": [ "new", "imported", "updated", "pending", "error", "deleted" ], "description": "See \"Datasource states\" under List datasources. `deleted` is only returned by scan and layer version datasource lists.\n", "example": "imported" }, "format": { "type": "string", "example": "application/json" }, "crs": { "type": "string", "example": "EPSG:4326" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "name": { "type": "string", "example": "OBJECTID" } } } }, "num_dims": { "type": "number", "example": 2 }, "num_features": { "type": "number", "example": 1500 }, "num_bands": { "type": "number", "nullable": true, "example": null }, "extent": { "type": "object", "properties": { "type": { "type": "string", "example": "Polygon" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "example": [ -1, -1 ] } } } }, "metadata": { "type": "number", "nullable": true, "example": null }, "geotags": { "description": "**Expandable**. URL of the datasource's geotags. Send the `Expand: geotags` header to get the geotags inline instead.\n", "oneOf": [ { "type": "string", "format": "url", "description": "URL of the datasource's geotags.", "example": "https://koordinates.com/services/api/v1/sources/36/datasources/1/geotags/" }, { "type": "array", "description": "*Expansion*: the datasource's geotags\n", "items": { "$ref": "#/components/schemas/DatasourceGeotag" } } ] }, "arcgis_folder_service_path": { "type": "string", "example": "Bob/MapServer" }, "arcgis_geometry_type": { "type": "string", "example": "esriGeometryPolygon" }, "arcgis_layer_name": { "type": "string", "example": "Geology" }, "arcgis_type": { "type": "string", "example": "Feature Layer" } } }, "DatasourceUrlOnly": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "example": "https://koordinates.com/services/api/v1/sources/36/datasources/1/" } } }, "LayerVersionTile": { "type": "object", "properties": { "id": { "type": "integer", "description": "The tile's id, unique within the layer's storage.", "example": 1234 }, "filename": { "type": "string", "description": "The tile's filename.", "example": "tile_0_0.tif" }, "format": { "type": "string", "description": "The tile's media type. Raster tiles are always stored as Cloud Optimized GeoTIFF, regardless of the source format.\n", "example": "image/tiff" }, "size": { "type": "integer", "description": "The tile's size in bytes, measured the way the layer's storage is billed. For most plans this is the uncompressed GeoTIFF equivalent (width × height × bytes per pixel), so it is usually larger than the compressed file in object storage. Plans billed on the size of the data as provided report the original file size instead, falling back to the uncompressed equivalent for tiles imported before the original size was recorded.\n", "example": 461858 }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the tile's space was reclaimed. Only present when listing with ```status=deleted```.\n", "example": "2026-06-23T14:30:45.123456Z" }, "deleted_by": { "type": "integer", "nullable": true, "description": "The id of the user who reclaimed the tile. Only present when listing with ```status=deleted```.\n", "example": 3 }, "last_revision": { "type": "string", "format": "date-time", "nullable": true, "description": "When the most recent version that still contained this tile was published. ```null``` if that version was an unpublished draft, or if no earlier version contained the tile. Only present when listing with ```status=deleted```.\n", "example": "2026-06-23T12:00:00Z" } } }, "LayerVersionTilesList": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of tiles matching the status filter.", "example": 1234 }, "size": { "type": "integer", "description": "Combined size in bytes of all tiles matching the status filter, measured the way the layer's storage is billed (see the tile ```size```). For ```status=unused``` this is the amount ```tiles/delete/``` would remove from the layer's billable size.\n", "example": 567890123 } } }, "tiles": { "type": "array", "items": { "$ref": "#/components/schemas/LayerVersionTile" } } } }, "LayerVersionTilesDeleteRequest": { "type": "object", "description": "Provide either ```tile_ids``` or ```all```. If both are given, ```all``` selects the tiles, but ```tile_ids```, if present, must still be a list of integers.\n", "properties": { "tile_ids": { "type": "array", "description": "The ids of the unused tiles to reclaim.", "items": { "type": "integer" }, "example": [ 1234, 1235, 1236 ] }, "all": { "type": "boolean", "description": "Reclaim every unused tile of this version.", "example": true } } }, "DOI": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "example": "https://doi.org/10.10000/ABC1-DEF9" }, "identifier": { "type": "string", "example": "doi:10.10000/ABC1-DEF9" } } }, "CreateDOIRequestString": { "type": "string", "example": "doi:10.10000/ABC1-DEF9" }, "CreateDOIRequestObject": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "example": "https://doi.org/10.10000/ABC1-DEF9" }, "identifier": { "type": "string", "example": "doi:10.10000/ABC1-DEF9" } } }, "CreateDOIRequest": { "oneOf": [ { "$ref": "#/components/schemas/CreateDOIRequestString" }, { "$ref": "#/components/schemas/CreateDOIRequestObject" } ] }, "LayerSettings": { "type": "object", "properties": { "autoupdate": { "$ref": "#/components/schemas/LayersAutoupdateSerializer" } } }, "DocumentsGet": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "name": { "type": "string", "example": "Soil Quality Report" }, "user": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "example": "http://koordinates.com/services/api/v1/services/api/v1/users/1/" }, "first_name\"": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "country": { "type": "string", "example": "US" } } }, "url": { "type": "string", "example": "http://koordinates.com/services/api/v1/documents/1/" }, "url_html": { "type": "string", "example": "http://koordinates.com/document/1-soil-quality-report/" }, "url_download": { "type": "string", "example": "http://koordinates.com/document/1-soil-quality-report/download/" }, "first_published_at": { "type": "string", "nullable": true, "example": null }, "published_at": { "type": "string", "nullable": true, "example": null }, "extension": { "type": "string", "example": "pdf" }, "file_size": { "type": "number", "example": 4 }, "file_size_formatted": { "type": "number", "example": "4.0 B" } } }, "createDocuments": { "type": "object", "properties": { "name": { "type": "string", "example": "Example Document" }, "data": { "type": "object", "properties": { "datasources": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/sources/5/datasources/1/" } } } } }, "createDocumentsResponse": { "type": "object", "properties": { "id": { "type": "number", "example": 2 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/documents/2/versions/2/" }, "created_at": { "type": "string", "example": "2015-04-12T21:43:59.200Z" }, "created_by\"": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "format": "url", "example": "http://koordinates.com/services/api/v1/services/api/v1/users/1/" }, "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "country": { "type": "string", "example": "US" } } } } }, "DocumentDetailsGet": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "name": { "type": "string", "example": "Soil Quality Report" }, "user": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "example": "http://koordinates.com/services/api/v1/services/api/v1/users/1/" }, "first_name\"": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "country": { "type": "string", "example": "US" } } }, "url": { "type": "string", "example": "http://koordinates.com/services/api/v1/documents/1/" }, "url_html": { "type": "string", "example": "http://koordinates.com/document/1-soil-quality-report/" }, "url_download": { "type": "string", "example": "http://koordinates.com/document/1-soil-quality-report/download/" }, "first_published_at": { "type": "string", "nullable": true, "example": null }, "published_at": { "type": "string", "nullable": true, "example": null }, "extension": { "type": "string", "example": "pdf" }, "file_size": { "type": "number", "example": 4 }, "file_size_formatted": { "type": "number", "example": "4.0 B" }, "description": { "type": "string", "example": "The soil quality report provides detailed information about soil conditions." }, "description_html": { "type": "string", "example": "

The soil quality report provides detailed information about soil conditions.

" }, "published_version": { "type": "string", "example": "http://koordinates.com/services/api/v1/documents/1/versions/1/" }, "latest_version": { "type": "string", "example": "http://koordinates.com/services/api/v1/documents/1/versions/1/" }, "this_version": { "type": "string", "example": "http://koordinates.com/services/api/v1/documents/1/versions/1/" }, "data": { "type": "object", "properties": { "datasources": { "type": "string", "format": "uri", "nullable": true, "example": null } } }, "categories": { "type": "array", "items": { "type": "string", "example": [] } }, "tags": { "type": "array", "items": { "type": "string", "example": [] } }, "license": { "type": "string", "nullable": true, "example": null }, "metadata": { "type": "string", "nullable": true, "example": null }, "permissions": { "type": "string", "format": "url", "example": "http://koordinates.com/services/api/v1/documents/1/permissions/" }, "publish_to_catalog_services": { "type": "boolean", "example": false } } }, "DocumentOwnerRequest": { "type": "object", "description": "Change the owner of a document. Supply exactly one of `user` or `group`.\nThe change takes effect immediately and is independent of the publishing\nworkflow.\n", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 } } }, "group": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 } } } } }, "deleteDocumentVirsionDetail": { "type": "object", "properties": { "error": { "type": "string", "example": "This version isn't a draft." } } }, "CatalogItemSerializer": { "type": "object", "properties": { "id": { "type": "string", "example": "c3TRfmHwdwpc9QY", "description": "Catalog item public ID (prefixed `c`).\n" }, "url": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/items/c3TRfmHwdwpc9QY/", "description": "API detail URL for this catalog item.\n" }, "type": { "type": "string", "example": "catalog-item", "description": "Always `catalog-item`.\n" }, "kind": { "type": "string", "example": "external", "description": "Item kind, derived from the catalog item subtype. One of `external`, `threedtiles` or `smalldata`.\n", "enum": [ "external", "threedtiles", "smalldata" ] }, "title": { "type": "string", "example": "Road Centerlines", "description": "Display title.\n" }, "description": { "type": "string", "description": "Markdown-formatted description.\n" }, "first_published_at": { "type": "string", "format": "date-time", "description": "Timestamp the item was first published, if ever.\n" }, "published_at": { "type": "string", "format": "date-time", "description": "Timestamp of the published version, if any.\n" }, "featured_at": { "type": "string", "format": "date-time", "description": "Timestamp this item was featured, if any.\n" }, "service_capabilities": { "type": "array", "description": "Capabilities provided by the item's enabled services.\n", "items": { "type": "string" } }, "user_capabilities": { "type": "array", "description": "Capabilities available to the requesting user for this item.\n", "items": { "type": "string" } }, "user_permissions": { "type": "array", "description": "Permissions the requesting user holds on this item.\n", "items": { "type": "string" } }, "is_starred": { "type": "boolean", "description": "Whether the requesting user has starred this item. Only present for authenticated requests.\n" }, "geometry_type": { "type": "string", "example": "polygon", "description": "Primary geometry type.\n" }, "services": { "type": "string", "format": "uri", "example": "https://{domain}/services/api/v1/items/c3TRfmHwdwpc9QY/services/", "description": "URL to the services configured for this catalog item. See the [Services documentation](#tag/Services).\n" } } }, "CatalogItemListItem": { "allOf": [ { "$ref": "#/components/schemas/CatalogItemSerializer" }, { "type": "object", "properties": { "public_access": { "type": "string", "nullable": true, "description": "The item's public access level, or null if not publicly shared.\n" } } } ] }, "CatalogItemList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/CatalogItemListItem" } }, "CatalogItemCreateRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "Display title for the catalog item" }, "kind": { "type": "string", "description": "Item subtype. One of `external`, `threedtiles` or `smalldata`. Required when creating a catalog item.\n", "enum": [ "external", "threedtiles", "smalldata" ] }, "description": { "type": "string", "description": "Markdown-formatted description" }, "categories": { "type": "array", "description": "Category keys/URLs to assign the item to.", "items": { "type": "string" } }, "tags": { "type": "array", "description": "Free-text tags.", "items": { "type": "string" } }, "permissions": { "type": "array", "description": "Direct permissions to set on the item.", "items": { "type": "object" } }, "settings": { "type": "object", "description": "Item settings, including metadata-locking flags (`lock_title_to_metadata`, `lock_description_to_metadata`, `lock_tags_to_metadata`).\n" }, "metadata": { "type": "object", "description": "Native metadata values keyed by field name." }, "config": { "type": "object", "nullable": true, "description": "Service configuration. Required when `kind` is `external`; ignored for other kinds.\n" }, "map_product": { "type": "object", "description": "Import data (datasources). Used for `threedtiles` items.\n" }, "publish": { "type": "boolean", "description": "Publish the new version immediately after creation." }, "user": { "type": "integer", "nullable": true, "description": "Id of the owning user. Mutually exclusive with `group`.\n" }, "group": { "type": "integer", "nullable": true, "description": "Id of the owning group. Mutually exclusive with `user`.\n" } }, "required": [ "title", "kind" ] }, "CatalogItemDetail": { "type": "object", "description": "The detail representation of a catalog item. Includes all fields of the list representation plus the version-specific and management fields below. Some fields are only present for particular item kinds (`map_product` for 3D Tiles items, `config` for external items).\n", "allOf": [ { "$ref": "#/components/schemas/CatalogItemSerializer" }, { "type": "object", "properties": { "num_views": { "type": "integer", "example": 1024, "description": "View count." }, "user": { "type": "object", "nullable": true, "description": "The owning user, if owned by a user." }, "group": { "type": "object", "nullable": true, "description": "The owning group, if owned by a group." }, "description_html": { "type": "string", "description": "The description rendered to HTML." }, "url_html": { "type": "string", "format": "uri", "description": "Browser URL for this item." }, "url_canonical": { "type": "string", "format": "uri", "description": "Canonical browser URL for this item." }, "active_publish": { "type": "object", "nullable": true, "description": "The in-progress publish for this version. Only present for draft versions.\n" }, "publisher": { "type": "object", "description": "The publishing user or group." }, "categories": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "array", "items": { "type": "string" } }, "geotags": { "type": "array", "items": { "type": "object" } }, "attachments": { "type": "array", "description": "Documents attached to this version.", "items": { "type": "object" } }, "settings": { "type": "object", "description": "Item settings/flags." }, "metadata": { "type": "string", "format": "uri", "description": "URL to the XML metadata endpoints for this version." }, "version": { "type": "object", "description": "The version represented by this response." }, "this_version": { "type": "string", "format": "uri" }, "published_version": { "type": "string", "format": "uri" }, "latest_version": { "type": "string", "format": "uri" }, "request_access": { "type": "string", "format": "uri", "description": "URL to request access to this item." }, "data": { "type": "object", "description": "3D Tiles items only; datasource configuration." }, "config": { "type": "object", "description": "External items only; external service configuration." } } } ] }, "CatalogItemVersion": { "type": "object", "properties": { "id": { "type": "integer", "description": "The version id." }, "url": { "type": "string", "format": "uri", "description": "API detail URL for this version." }, "created_at": { "type": "string", "format": "date-time", "description": "When the version was created." }, "status": { "type": "string", "nullable": true, "description": "Import status. Only present when the version has an import (3D Tiles items).\n", "enum": [ "importing", "completed", "error", "cancelled" ] }, "progress": { "type": "number", "nullable": true, "description": "Import progress between 0 and 1. Only present when the version has an import.\n" } } }, "CatalogItemVersionList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/CatalogItemVersion" } }, "CatalogItemAttachmentRequest": { "type": "object", "properties": { "document": { "type": "string", "format": "uri", "description": "URL of the Document resource to attach." } }, "required": [ "document" ] }, "LicenseItemSerializer": { "type": "object", "properties": { "id": { "type": "integer", "example": "1" }, "title": { "title": "License Title", "type": "string", "example": "Creative Commons Attribution 3.0 New Zealand" }, "type": { "type": "string", "example": "cc-by" }, "jurisdiction": { "type": "string", "example": "nz" }, "version": { "type": "string", "example": "3.0" }, "url": { "type": "string", "example": "https://testserver.com/services/api/v1.x/licenses/1" }, "slug": { "type": "string", "example": "attribution-3-0-new-zealand" }, "text": { "type": "string", "example": "THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENCE." }, "url_external": { "type": "string", "example": "http://creativecommons.org/licenses/by/3.0/nz/" }, "linked_item_counts": { "description": "Layers and documents this license belongs to", "type": "object", "properties": { "layers": { "type": "integer" }, "documents": { "type": "integer" } } } } }, "LicenseList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/LicenseItemSerializer" } }, "CreateLicenseRequest": { "type": "object", "properties": { "title": { "type": "string", "example": "The Unlicense" }, "text": { "type": "string", "description": "Body of the license text." }, "slug": { "type": "string", "description": "URL-friendly name for this license. Will be generated automatically if not provided." }, "url_external": { "type": "string" } } }, "UpdateLicenseRequest": { "type": "object", "properties": { "title": { "type": "string", "example": "The Unlicense" }, "text": { "type": "string" }, "slug": { "type": "string", "description": "URL-friendly name for this license. Will be generated automatically if not provided." }, "url_external": { "type": "string" }, "description": { "type": "string", "example": "These points are totally fictional!" }, "collected": { "type": "string", "format": "date", "example": "2013-01-01" }, "license": { "$ref": "#/components/schemas/LayersLicenseSerializer" }, "supplier_reference": { "type": "string", "example": "TIVPAS" }, "version_reference": { "type": "string", "example": "added more data" }, "default_style_id": { "type": "number", "example": 3 }, "publish": { "type": "boolean", "example": true }, "mapstream_id": { "type": "number", "example": 3 }, "categories": { "type": "string", "example": "topographic/nz-topo-offshore-islands-data/terrain" }, "tags": { "type": "array", "example": "tag2, tag2" }, "permissions": { "type": "string", "format": "url", "example": "topographic/nz-topo-offshore-islands-data/terrain" }, "publish_to_catalog_services": { "type": "boolean", "example": true }, "autoupdate": { "$ref": "#/components/schemas/LayersAutoupdateSerializer" }, "data": { "$ref": "#/components/schemas/LayersDataSerializer" }, "tilegrids": { "type": "array", "example": "[]" } }, "required": [ "data" ] }, "CoordinateSystemList": { "type": "array", "minimum": 0, "items": { "$ref": "#/components/schemas/CoordinateSystemListItem" } }, "DataSourceUser": { "type": "object", "properties": { "id": { "type": "number", "example": 3 }, "name": { "type": "string", "example": "Bob Jones" } } }, "Sources": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/" }, "name": { "type": "string", "example": "harbour-images.zip" }, "type": { "type": "string", "example": "upload" }, "datasource_count": { "type": "integer", "description": "Number of datasources this source's last scan found.", "example": 12 }, "description": { "type": "string", "example": "" }, "description_html": { "type": "string", "example": "" }, "categories": { "type": "string", "example": "[]" }, "user": { "type": "object", "properties": { "id": { "type": "number", "example": 3 }, "name": { "type": "string", "example": "Bob Jones" } }, "$ref": "#/components/schemas/DataSourceUser" }, "last_scanned_at": { "type": "string", "example": null, "nullable": true }, "scan_schedule": { "type": "string", "example": null, "nullable": true }, "options": { "type": "string", "example": "{}" }, "metadata": { "type": "string", "example": null, "nullable": true } } }, "SourcePostOptions": { "type": "object", "properties": { "username": { "type": "string", "example": "bob" }, "password": { "type": "string", "example": "sekret_p@55w0rd" } } }, "createSources": { "type": "object", "properties": { "name": { "type": "string", "example": "Bob's ArcGIS 10 Server" }, "type": { "type": "string", "example": "arcgis" }, "description": { "type": "string", "example": "All of Bob's data" }, "categories": { "type": "string", "example": "[]" }, "user": { "type": "number", "example": 3 }, "options": { "type": "object", "$ref": "#/components/schemas/SourcePostOptions" }, "url_remote": { "type": "string", "format": "url", "example": "https://bob.example.com/ArcGIS/rest/services" }, "scan_schedule": { "type": "string", "example": "@daily" } } }, "SourceUserExample": { "type": "object", "properties": { "id": { "type": "number", "example": 3 }, "name": { "type": "string", "example": "Bob Jones" } } }, "createSourcesResponse": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/2/" }, "name": { "type": "string", "example": "Bob's ArcGIS 10 Server" }, "type": { "type": "string", "example": "arcgis" }, "datasource_count": { "type": "integer", "description": "Number of datasources this source's last scan found.", "example": 12 }, "description": { "type": "string", "example": "All of Bob's data" }, "description_html": { "type": "string", "example": "

All of Bob's data

" }, "categories": { "type": "string", "example": "[]" }, "user": { "type": "object", "$ref": "#/components/schemas/SourceUserExample" }, "last_scanned_at": { "type": "string", "example": null, "nullable": true }, "scan_schedule": { "type": "string", "example": "@daily", "nullable": true }, "options": { "type": "string", "example": "{}" }, "metadata": { "type": "string", "example": null, "nullable": true }, "url_remote": { "type": "string", "format": "url", "example": "https://bob.example.com/ArcGIS/rest/services" } } }, "editSource": { "type": "object", "properties": { "description": { "type": "string", "example": "Harbour Imagery (4m/px)" } } }, "editSourceResponse": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/" }, "name": { "type": "string", "example": "harbour-images.zip" }, "type": { "type": "string", "example": "upload" }, "datasource_count": { "type": "integer", "description": "Number of datasources this source's last scan found.", "example": 12 }, "description": { "type": "string", "example": "Harbour Imagery (4m/px)" }, "description_html": { "type": "string", "example": "

Harbour Imagery (4m/px)

" }, "categories": { "type": "string", "example": "[]" }, "user": { "type": "object", "properties": { "id": { "type": "number", "example": 3 }, "name": { "type": "string", "example": "Bob Jones" } }, "$ref": "#/components/schemas/DataSourceUser" }, "last_scanned_at": { "type": "string", "example": null, "nullable": true }, "scan_schedule": { "type": "string", "example": null, "nullable": true }, "options": { "type": "string", "example": "{}" }, "metadata": { "type": "string", "example": null, "nullable": true } } }, "SourceScans": { "type": "object", "properties": { "id": { "type": "number", "example": 4 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/scans/4/" }, "status": { "type": "string", "example": "completed" }, "started_at": { "type": "string", "example": "2013-10-13T02:53:28Z" }, "completed_at": { "type": "string", "example": "2012-10-13T02:53:47Z" }, "last_activity_at": { "type": "string", "description": "When the scan last wrote to its log (flushed at least every 10 seconds while running).", "example": "2012-10-13T02:53:47Z" }, "change_counts": { "type": "object", "properties": { "deleted": { "type": "number", "example": 0 }, "updated": { "type": "number", "example": 3 }, "added": { "type": "number", "example": 0 } } }, "log": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/scans/4/log/" } } }, "startSourceScan": { "type": "object", "properties": { "datasources": { "type": "array", "minItems": 1, "description": "URLs of datasources belonging to this source. Only those datasources\nare scanned.\n", "items": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/datasources/4/" } } } }, "SourceScanDetailsGet": { "type": "object", "properties": { "id": { "type": "number", "example": 4 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/scans/4/" }, "status": { "type": "string", "example": "completed" }, "started_at": { "type": "string", "example": "2013-10-13T02:53:28Z" }, "completed_at": { "type": "string", "example": "2012-10-13T02:53:47Z" }, "last_activity_at": { "type": "string", "description": "When the scan last wrote to its log (flushed at least every 10 seconds while running).", "example": "2012-10-13T02:53:47Z" }, "change_counts": { "type": "object", "properties": { "deleted": { "type": "number", "example": 0 }, "updated": { "type": "number", "example": 0 }, "added": { "type": "number", "example": 0 } } }, "log": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/scans/4/log/" }, "progress": { "type": "number", "format": "float", "example": 1 } } }, "Datasources": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "url": { "type": "string", "format": "url", "example": "https://{domain}/services/api/v1/sources/1/datasources/1/" }, "title": { "type": "string", "description": "The datasource's title. Falls back to a name derived from the file name (or the layer name within a multi-layer file) when the source data provides no title.", "example": "Null Island Polygons" }, "data_type": { "type": "string", "example": "vector" }, "geometry_type": { "type": "string", "example": "polygon" }, "updated_at": { "type": "string", "example": "2013-10-13T02:53:46Z" }, "state": { "type": "string", "enum": [ "new", "imported", "updated", "pending", "error", "deleted" ], "description": "See \"Datasource states\" under List datasources. `deleted` is only returned by scan and layer version datasource lists.\n", "example": "imported" }, "arcgis_folder_service_path": { "type": "string", "example": "Bob/MapServer" }, "arcgis_geometry_type": { "type": "string", "example": "esriGeometryPolygon" }, "arcgis_layer_name": { "type": "string", "example": "Null Island" }, "arcgis_type": { "type": "string", "example": "Feature Layer" } } }, "DatasourceMetadata": { "type": "object", "properties": { "creator": { "type": "string", "example": "Bob Jones and Associates" }, "subject": { "type": "string", "example": "hydro" }, "description": { "type": "string", "example": "Some nice colourful aerial photos of the Auckland Harbour." }, "date": { "type": "string", "example": "2013-01-01" }, "type": { "type": "string", "example": "raster" }, "language": { "type": "string", "example": "eng" } } }, "ApiKeyProperty": { "type": "string", "description": "Your Koordinates API key. Not required if using session authentication (cookie) or the Authorization header (e.g., 'Authorization: Key ').", "example": "abc123def456" }, "LongitudeProperty": { "type": "number", "description": "Longitude of the point you want to query", "example": 174.77694 }, "LatitudeProperty": { "type": "number", "description": "Latitude of the point you want to query", "example": -41.27831 }, "RadiusProperty": { "type": "integer", "description": "Distance in meters to query around the specified point", "minimum": 0, "maximum": 100000 }, "GeometryProperty": { "type": "boolean", "description": "Whether to include the geometry for each feature result", "default": false }, "WithFieldNamesProperty": { "type": "boolean", "description": "Whether to include an ordered list of field names. Availability: 1.1", "default": false }, "CallbackProperty": { "type": "string", "description": "Only available for JSON formats. The name of the JSONP callback function to wrap the response in", "example": "myCallback" } }, "parameters": { "SearchQParameter": { "name": "q", "in": "query", "required": false, "description": "Free-text search. Terms are matched against the title, description, tags, category and geotag names of each item, plus its publisher's name, its field names and (for sets) its member layers. Any term may match (terms are OR-ed); items matching more terms, or matching in the title, rank higher. When `q` is given and `sort` is not, results are ordered by relevance.\n", "schema": { "type": "string" }, "example": "coal" }, "DataSortParameter": { "name": "sort", "in": "query", "required": false, "description": "Sort order. Prefix with `-` to reverse. Defaults to relevance, which without `q` is effectively unordered. An unknown value is a `400`.\n", "schema": { "type": "string", "enum": [ "name", "-name", "popularity", "created_at", "-created_at", "updated_at", "-updated_at", "featured_at", "-featured_at", "billing_size", "-billing_size" ] } }, "SearchFacetsParameter": { "name": "facets", "in": "query", "required": false, "description": "When `true`, return facet counts for the current filters instead of the result list. See *Faceting* above.\n", "schema": { "type": "boolean" } }, "SearchIdParameter": { "name": "id", "in": "query", "required": false, "description": "Filter by item ID (repeatable).", "schema": { "type": "string" } }, "SearchKindParameter": { "name": "kind", "in": "query", "required": false, "description": "Filter by item type and/or data type (repeatable, OR-ed). `layer`/`table` also match Kart repository datasets; `vector` matches `point`, `linestring` and `polygon` data; `attribute-grid` matches raster attribute tables. `repo` excludes automatically created mirror and point-cloud repositories; use `repo-all` for every repository, or `repo-mirror`, `repo-vector`, `repo-table`, `repo-raster` and `repo-pointcloud` for one kind. `datasource` (indexed datasources) requires a data pack, and is a `400` otherwise.\n", "schema": { "type": "string", "enum": [ "layer", "table", "set", "document", "source", "repo", "repo-all", "repo-mirror", "repo-vector", "repo-table", "repo-raster", "repo-pointcloud", "mapviewer", "catalog-item", "fork", "vector", "raster", "grid", "attribute-grid", "pointcloud", "arcgis", "wfs", "postgres", "cifs", "s3", "kart", "url", "web", "info", "upload", "threedtiles", "external", "smalldata", "datasource" ] } }, "SearchGeometryTypeParameter": { "name": "data.geometry_type", "in": "query", "required": false, "description": "Filter vector data by geometry type (repeatable, OR-ed).", "schema": { "type": "string", "enum": [ "point", "linestring", "polygon" ] } }, "SearchStorageParameter": { "name": "data.storage", "in": "query", "required": false, "description": "`kart` returns only Kart repository datasets; `classic` excludes them. Giving both is the same as giving neither.\n", "schema": { "type": "string", "enum": [ "classic", "kart" ] } }, "SearchPublicParameter": { "name": "public", "in": "query", "required": false, "description": "Filter by public/shared status. Anonymous requests only ever see public items.\n", "schema": { "type": "boolean" } }, "SearchIsStarredParameter": { "name": "is_starred", "in": "query", "required": false, "description": "Filter to items the authenticated user has (or has not) starred. Ignored for anonymous requests.\n", "schema": { "type": "boolean" } }, "SearchIsPinnedParameter": { "name": "is_pinned", "in": "query", "required": false, "description": "`true` returns items pinned to this site; `false` returns items from other sites that are not pinned here. Site administrators only; ignored otherwise.\n", "schema": { "type": "boolean" } }, "SearchHasRepoParameter": { "name": "has_repo", "in": "query", "required": false, "description": "`true` returns items backed by a Kart repository (and the repositories themselves); `false` returns items without one.\n", "schema": { "type": "boolean" } }, "SearchPublishingParameter": { "name": "publishing", "in": "query", "required": false, "description": "Filter by whether the layer/table is currently being published. When `true`, returns only items whose active publish is in the `publishing` state (i.e. the publish job is actively running). Items whose active publish is queued (`waiting-for-time`, `waiting-for-items`) or has errored are excluded — see `publish_errored` for the errored case.\n", "schema": { "type": "boolean" }, "example": true }, "SearchPublishErroredParameter": { "name": "publish_errored", "in": "query", "required": false, "description": "Filter by whether the layer/table's active publish has errored. When `true`, returns only items whose active publish is in the `errored` state.\n", "schema": { "type": "boolean" }, "example": true }, "SearchAutoupdateParameter": { "name": "autoupdate", "in": "query", "required": false, "description": "Filter by whether automatic updates are enabled.", "schema": { "type": "boolean" } }, "SearchFirstImportParameter": { "name": "first_import", "in": "query", "required": false, "description": "Filter by whether the item's data is from its first import (its data has never been updated).\n", "schema": { "type": "boolean" } }, "SearchCropLayerEligibleParameter": { "name": "crop_layer_eligible", "in": "query", "required": false, "description": "Filter by whether the layer can be used as a crop layer source: a polygon layer with at most 1000 features.\n", "schema": { "type": "boolean" } }, "SearchUpdatableParameter": { "name": "updatable", "in": "query", "required": false, "description": "`true` returns items whose data sources have newer data available. `false` is ignored.\n", "schema": { "type": "boolean" } }, "SearchIsFeaturedParameter": { "name": "is_featured", "in": "query", "required": false, "description": "Filter by whether the item is featured.", "schema": { "type": "boolean" } }, "SearchHasZParameter": { "name": "has_z", "in": "query", "required": false, "description": "Filter vector data by whether geometries have Z values.", "schema": { "type": "boolean" } }, "SearchIsImageryParameter": { "name": "is_imagery", "in": "query", "required": false, "description": "Filter raster data by whether it is imagery.", "schema": { "type": "boolean" } }, "SearchHasPkParameter": { "name": "has_pk", "in": "query", "required": false, "description": "Filter vector data by whether it has a primary key.", "schema": { "type": "boolean" } }, "SearchRasterBandParameter": { "name": "raster_band", "in": "query", "required": false, "description": "Filter raster data by band colour interpretation (repeatable). Unlike other repeatable filters, all given bands must be present.\n", "schema": { "type": "string", "enum": [ "red", "green", "blue", "gray", "alpha" ] } }, "SearchRasterResolutionLtParameter": { "name": "raster_resolution.lt", "in": "query", "required": false, "description": "Filter raster data to a resolution finer than this (metres).", "schema": { "type": "number" } }, "SearchRasterResolutionGtParameter": { "name": "raster_resolution.gt", "in": "query", "required": false, "description": "Filter raster data to a resolution coarser than this (metres).", "schema": { "type": "number" } }, "SearchCreatedBeforeParameter": { "name": "created_at.before", "in": "query", "required": false, "description": "Filter to items created before this time (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, "SearchCreatedAfterParameter": { "name": "created_at.after", "in": "query", "required": false, "description": "Filter to items created after this time (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, "SearchUpdatedBeforeParameter": { "name": "updated_at.before", "in": "query", "required": false, "description": "Filter to items updated before this time (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, "SearchUpdatedAfterParameter": { "name": "updated_at.after", "in": "query", "required": false, "description": "Filter to items updated after this time (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, "SearchFeaturedBeforeParameter": { "name": "featured_at.before", "in": "query", "required": false, "description": "Filter to items featured before this time (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, "SearchFeaturedAfterParameter": { "name": "featured_at.after", "in": "query", "required": false, "description": "Filter to items featured after this time (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, "SearchPtParameter": { "name": "pt", "in": "query", "required": false, "description": "A WGS84 point as `lon,lat`. Filters to items whose extent is within `distance` of the point; ignored unless `distance` is also given.\n", "schema": { "type": "string" }, "example": "174.77,-41.29" }, "SearchDistanceParameter": { "name": "distance", "in": "query", "required": false, "description": "Distance from `pt` in kilometres.", "schema": { "type": "integer" } }, "SearchGeometryParameter": { "name": "geometry", "in": "query", "required": false, "description": "A WGS84 polygon or multipolygon, as WKT or GeoJSON. Filters to items whose extent intersects it.\n", "schema": { "type": "string" } }, "SearchServiceParameter": { "name": "service", "in": "query", "required": false, "description": "Filter to items with an active service offering this capability (repeatable, OR-ed).\n", "schema": { "type": "string", "enum": [ "map", "map-vector-tile", "map-raster-tile", "map-wmts", "map-copc", "map-3d-tiles", "map-ifc", "map-esri-rest", "map-small-data", "api", "api-esri-rest", "api-ogc-wfs", "api-ogc-wfschangesets" ] } }, "SearchLicenseParameter": { "name": "license", "in": "query", "required": false, "description": "Filter by license ID or URL, or `true`/`false` for any/no license (repeatable). An unknown license is a `400`.\n", "schema": { "type": "string" } }, "SearchLicenseTypeParameter": { "name": "license.type", "in": "query", "required": false, "description": "Filter by license type (repeatable, OR-ed): `custom`, `commercial`, `cc`, or a Creative Commons variant such as `cc-by`, `cc-by-sa`, `cc-by-nc-nd`. Prefix with `-` to exclude.\n", "schema": { "type": "string" }, "example": "cc-by" }, "SearchLicenseJurisdictionParameter": { "name": "license.jurisdiction", "in": "query", "required": false, "description": "Filter Creative Commons licenses by jurisdiction code, e.g. `nz` (repeatable).\n", "schema": { "type": "string" } }, "SearchLicenseVersionParameter": { "name": "license.version", "in": "query", "required": false, "description": "Filter licenses by version, e.g. `4.0` (repeatable).", "schema": { "type": "string" } }, "SearchCategoryParameter": { "name": "category", "in": "query", "required": false, "description": "Filter by category URL, e.g. `cadastral/parcels`, including descendant categories (repeatable).\n", "schema": { "type": "string" } }, "SearchGeotagParameter": { "name": "geotag", "in": "query", "required": false, "description": "Filter by geotag URL, e.g. `global/oceania/new-zealand` (repeatable).\n", "schema": { "type": "string" } }, "SearchTagParameter": { "name": "tag", "in": "query", "required": false, "description": "Filter by tag (repeatable).", "schema": { "type": "string" } }, "SearchGroupParameter": { "name": "group", "in": "query", "required": false, "description": "Filter by owning group ID or URL (repeatable). Unknown groups are ignored, but a `400` if none of the given groups exist.\n", "schema": { "type": "string" } }, "SearchAccessGroupParameter": { "name": "access_group", "in": "query", "required": false, "description": "Filter to items whose access requests go to this group ID or URL (repeatable).\n", "schema": { "type": "string" } }, "SearchOrgParameter": { "name": "org", "in": "query", "required": false, "description": "Filter by organisation ID (repeatable). Prefix with `-` to exclude.\n", "schema": { "type": "string" } }, "SearchUserParameter": { "name": "user", "in": "query", "required": false, "description": "Filter by owning user public ID, or `me` (repeatable). Prefix with `-` to exclude.\n", "schema": { "type": "string" } }, "SearchFromParameter": { "name": "from", "in": "query", "required": false, "description": "Include data from other sites (API v1.x only; a `400` in v1). Values: a site domain, `domain:group_id` for one group on a site, `org:slug` for an organisation, or `all` for every site whose data is visible to you. Prefix with `-` to exclude (repeatable). Ignored on sites that do not allow inter-site data.\n", "schema": { "type": "string" }, "example": "data.linz.govt.nz" }, "SearchContextParameter": { "name": "context", "in": "query", "required": false, "description": "A site domain. `group` filters and `facets=true` group counts are resolved against that site's groups instead of this one's. Requires authentication and access to the site.\n", "schema": { "type": "string" } }, "SearchRoleParameter": { "name": "role", "in": "query", "required": false, "description": "Only return items the authenticated user holds this permission on. Defaults to `find`.\n", "schema": { "type": "string", "enum": [ "find", "view", "download", "admin" ] } }, "SearchVersionStatusParameter": { "name": "version.status", "in": "query", "required": false, "description": "Filter by the import status of the listed version (repeatable).", "schema": { "type": "string", "enum": [ "OK", "ERROR", "IMPORTING", "CANCELLED", "NEW" ] } }, "SearchHasDraftParameter": { "name": "has_draft", "in": "query", "required": false, "description": "When `true`, only return items whose latest version is an unpublished draft.\n", "schema": { "type": "boolean" } }, "SearchActivityParameter": { "name": "activity", "in": "query", "required": false, "description": "Only return layers/tables with a job of this kind on the listed version (repeatable; values are ORed). `importing` is a first import, `updating` an import that replaces existing data, `publishing` an active publish. Includes both running and errored jobs unless narrowed with `errored`.\n", "schema": { "type": "string", "enum": [ "importing", "updating", "publishing" ] } }, "SearchErroredParameter": { "name": "errored", "in": "query", "required": false, "description": "`true` returns only layers/tables whose import, update or publish has errored; `false` excludes them. Combine with `activity` to narrow to one kind of job.\n", "schema": { "type": "boolean" } }, "SearchSortParameter": { "name": "sort", "in": "query", "required": false, "description": "Sort order. Prefix with `-` to reverse. Defaults to relevance, which without `q` is effectively unordered. An unknown value is a `400`.\n", "schema": { "type": "string", "enum": [ "name", "-name", "popularity", "created_at", "-created_at", "updated_at", "-updated_at", "featured_at", "-featured_at" ] } }, "KeyParameter": { "name": "key", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyProperty" } }, "SetParameter": { "name": "set", "in": "query", "required": true, "description": "The ID of the set to query. If the set contains more than 500 layers, the query will fail.", "schema": { "type": "integer" } }, "XParameter": { "name": "x", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/LongitudeProperty" } }, "YParameter": { "name": "y", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/LatitudeProperty" } }, "RadiusParameter": { "name": "radius", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/RadiusProperty" }, { "default": 1000 } ] } }, "GeometryParameter": { "name": "geometry", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/GeometryProperty" } }, "WithFieldNamesParameter": { "name": "with_field_names", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WithFieldNamesProperty" } }, "PrecisionParameter": { "name": "precision", "in": "query", "required": false, "description": "Number of decimal places for GeoJSON coordinates in the response. 8 decimal places gives ~1.1mm precision at the equator.", "schema": { "type": "integer", "minimum": 0, "maximum": 15, "default": 8 } }, "CallbackParameter": { "name": "callback", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CallbackProperty" } }, "SetMaxResultsParameter": { "name": "max_results", "in": "query", "required": false, "description": "Maximum number of features to return for each layer", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 } }, "RasterLayerParameter": { "name": "layer", "in": "query", "required": true, "description": "The ID(s) of the raster or grid layer(s) to get results from. Can be a single layer ID or multiple comma-separated IDs. Maximum 10 layers.", "schema": { "type": "string" }, "example": "1132,1145,1156" }, "VectorLayerParameter": { "name": "layer", "in": "query", "required": true, "description": "The ID(s) of the vector layer(s) to get results from. Can be a single layer ID or multiple comma-separated IDs. Maximum 20 layers.", "schema": { "type": "string" }, "example": "743,856,912" }, "VectorMaxResultsParameter": { "name": "max_results", "in": "query", "required": false, "description": "Maximum number of features to return for each layer", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } } } }, "x-tagGroups": [ { "name": "Data Services", "tags": [ "Exports", "Raster Query", "Vector Query", "Set Query", "Coordinate Systems" ] }, { "name": "Data Management", "tags": [ "Data Management Overview", "Data Catalog", "Data Sources", "Layers", "Documents", "Repositories", "Catalog Items", "Services", "Data Object Identifiers", "Notifications" ] }, { "name": "Administration", "x-displayName": "Site Administration", "tags": [ "Users", "Groups", "Licenses", "Categories", "Pinning" ] } ] }