Site Admin APIs

Get Started Account and Support File Formats and Data Types Find and Export Data Import Data Manage Your Site Plugins Publish Data Query API and Web Services Site Admin APIs
API Admin Glossary API Client Library Cartography API Data Catalog API Data Object Identifiers API Data Sources API Documents API Export API Feedback API Introducing the Admin API Layers & tables API License API Metadata API Permissions API Publishing API Redaction API Sets API Set scopes for an API token Users & Groups API
Update Data Users and Groups Desktop App Frequently Asked Questions
  1. Home
  2. Site Admin APIs
  3. Documents API

Documents API

For finding, creating and editing documents.

Documents list

GET /documents/
List documents

Response 200

Headers

Content-Type: application/json

Body

[{
    "id": 1, 
    "name": "Soil Quality Report", 
    "user": {
        "id": 1, 
        "url": "http://koordinates.com/services/api/v1/services/api/v1/users/1/", 
        "first_name": "Jane", 
        "last_name": "Doe", 
        "country": "US"
    },
    "url": "http://koordinates.com/services/api/v1/documents/1/", 
    "url_html": "http://koordinates.com/document/1-soil-quality-report/", 
    "url_download": "http://koordinates.com/document/1-soil-quality-report/download/", 
    "first_published_at": null, 
    "published_at": null, 
    "extension": "pdf", 
    "file_size": 4, 
    "file_size_formatted": "4.0 B"
}]
POST /documents/
Create document

Note that documents can only be created from sources with the data type document.

Request

Headers

Content-Type: application/json

Body

{
      "name": "Example Document",
      "user": "https://{domain}/services/api/v1/users/1/",
      "data": {
          "datasources": "https://{domain}/services/api/v1/sources/5/datasources/1/"
      }
  }

Response 201

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1/documents/2/versions/2/

Body

{
    "id": 2, 
    "url": "https://{domain}/services/api/v1/documents/2/versions/2/", 
    "created_at": "2015-04-12T21:43:59.200Z", 
    "created_by": {
        "id": 1, 
        "url": "http://koordinates.com/services/api/v1/services/api/v1/users/1/", 
        "first_name": "Jane", 
        "last_name": "Doe", 
        "country": "US"
    }
}

Document detail

GET /documents/{id}/
Retrieve a document

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1, 
    "name": "Soil Quality Report", 
    "user": {
        "id": 1, 
        "url": "http://koordinates.com/services/api/v1/services/api/v1/users/1/", 
        "first_name": "Jane", 
        "last_name": "Doe", 
        "country": "US"
    },
    "url": "http://koordinates.com/services/api/v1/documents/1/", 
    "url_html": "http://koordinates.com/document/1-soil-quality-report/", 
    "url_download": "http://koordinates.com/document/1-soil-quality-report/download/", 
    "first_published_at": null, 
    "published_at": null, 
    "extension": "pdf", 
    "file_size": 4, 
    "file_size_formatted": "4.0 B"
    "description": "The soil quality report provides detailed information about soil conditions.", 
    "description_html": "<p>The soil quality report provides detailed information about soil conditions.</p>", 
    "published_version": "http://koordinates.com/services/api/v1/documents/1/versions/1/", 
    "latest_version": "http://koordinates.com/services/api/v1/documents/1/versions/1/", 
    "this_version": "http://koordinates.com/services/api/v1/documents/1/versions/1/", 
    "data": {
        "datasource": null
    }, 
    "categories": [], 
    "tags": [], 
    "license": null, 
    "metadata": null, 
    "permissions": "http://koordinates.com/services/api/v1/documents/1/permissions/", 
    "publish_to_catalog_services": false
}
DELETE /documents/{id}/
Delete a document

Response 204

Document versions

GET /documents/{id}/versions/
List document versions

Response 200

Body

[{
    "id": 2, 
    "url": "https://{domain}/services/api/v1/documents/2/versions/2/", 
    "created_at": "2015-04-12T21:43:59.200Z", 
    "created_by": {
        "id": 1, 
        "url": "http://koordinates.com/services/api/v1/services/api/v1/users/1/", 
        "first_name": "Jane", 
        "last_name": "Doe", 
        "country": "US"
    }
}]
POST documents/{id}/versions/
Create document version

Document version detail

GET /documents/{id}/versions/{version}/
Retrieve document version
PUT /documents/{id}/versions/{version}/
Update document version
DELETE /documents/{id}/versions/{version}/
Delete document version

Deletes this draft version (revert to published). 

Response 204

Response 405

Headers

Content-Type: application/json

Body

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

Response 409

Headers

Content-Type: application/json

Body

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

Document version publishing

POST /documents/{id}/versions/{version}/import/
Publish document version