Documents API

For finding, creating and editing documents.

Documents list

GET/documents/List documents

Returns a paginated list of the documents you can see. Use page, page_size (maximum 200), q and sort to page, search and order the results. The X-Resource-Range header gives the range and total.

Response 200

Headers

Content-Type: application/json

Body

[{
    "id": 1,
    "title": "Soil Quality Report",
    "user": {
        "id": 1,
        "url": "https://{domain}/services/api/v1.x/users/1/",
        "first_name": "Jane",
        "last_name": "Doe",
        "country": "US"
    },
    "url": "https://{domain}/services/api/v1.x/documents/1/",
    "url_html": "https://{domain}/document/1-soil-quality-report/",
    "url_download": "https://{domain}/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. Required fields are title, data.datasource (the URL of a datasource with the data type document) and either group or user (an ID; some sites only allow groups to own data). The document is published immediately, so there is no draft version after the create.

Request

Headers

Content-Type: application/json

Body

{
    "title": "Example Document",
    "group": 1,
    "data": {
        "datasource": "https://{domain}/services/api/v1.x/sources/5/datasources/1/"
    }
}

Response 201

Headers

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

Body: the document detail, as in Retrieve a document, plus a version object for the new version (id, url, created_at, created_by).

GET/documents/drafts/List document drafts

Lists the draft version of each document. If the most recent version of a document has already been published, it won’t appear here.

GET/documents/latest/List latest document versions

Lists the latest version of each document that you can see: the draft version for documents you can administer, and the published version for all others.

Document detail

GET/documents/{id}/Retrieve a document

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "title": "Soil Quality Report",
    "user": {
        "id": 1,
        "url": "https://{domain}/services/api/v1.x/users/1/",
        "first_name": "Jane",
        "last_name": "Doe",
        "country": "US"
    },
    "url": "https://{domain}/services/api/v1.x/documents/1/",
    "url_html": "https://{domain}/document/1-soil-quality-report/",
    "url_download": "https://{domain}/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": "https://{domain}/services/api/v1.x/documents/1/versions/1/",
    "latest_version": "https://{domain}/services/api/v1.x/documents/1/versions/1/",
    "this_version": "https://{domain}/services/api/v1.x/documents/1/versions/1/",
    "data": {
        "datasource": "https://{domain}/services/api/v1.x/sources/5/datasources/1/"
    },
    "categories": [],
    "tags": [],
    "license": null,
    "metadata": null,
    "permissions": "https://{domain}/services/api/v1.x/documents/1/permissions/",
    "publish_to_catalog_services": false
}

DELETE/documents/{id}/Delete a document

Deletes the document and all its versions.

Response 204

Document versions

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

Response 200

Body

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

POST/documents/{id}/versions/Create document version

Creates a draft version of the document, copying the latest version. Returns 201 with a Location header for the new version and the document detail in the body. If the document already has a draft, returns 409 with {"already-exists": "This document already has a draft version"}.

Document version detail

GET/documents/{id}/versions/{version}/Retrieve document version

PUT/documents/{id}/versions/{version}/Update document version

Edits a draft version (for example title or description). Returns 200 with the document detail, or 405 with {"not-draft": "This version isn't a draft, so you can't edit it"} if the version has been published.

DELETE/documents/{id}/versions/{version}/Delete document version

Deletes this draft version (revert to published).

Response 204

No body.

Response 405

Headers

Content-Type: application/json

Body

{"not-draft": "This version isn't a draft, so you can't delete it"}

Document version publishing

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

No POST data. Returns 201 with a publish object and a Location header pointing at it.

POST/documents/{id}/versions/publish/Create and publish document version

Creates a new version of the document and publishes it immediately. If the document already has a draft version, a 409 response is returned with {"already-exists": "This document already has a draft version"}.