Documents

Import Documents

Required scope: public-api:write

Description

The document import does both create and update documents. The import remembers the externalId / systemName pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the externalId when you want to update documents). The document import in Livingdocs is asynchronous. You post a batch of documents that you want to import and get back an id with which you can query later to get your result.

Use Cases
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/v1/import/documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @- << EOF
  {
    "systemName": "identifier-for-your-system",
    "webhook": "https://my-domain.com/webhooks/document-import",
    "documents": []
  }
EOF

Endpoint

POST api/v1/import/documents

Parameters

NameTypeRequiredNotes
systemNamestringxIdentifier for the system you are importing from, e.g. an archive
webhookuriEndpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview.
contextobjectAn object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.
documentsarrayxAn array of documents to import. Each entry is an object with the following keys:

id: a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project.
title: the title that the document should get in livingdocs
checksum: string to identify changes, e.g. an updated_at timestamp
contentType: the content type that the document should get in livingdocs
publishControl: An object with
- firstPublicationDate: sets the first publication date
- significantPublicationDate: (Added in: release-2023-07) sets a date which can be used by deliveries to display to viewers
- visiblePublicationDateOverride: (Added in: release-2024-01) sets a date which can be used by deliveries to display to viewers
- lastPublicationDate: sets the most recent publication date
The autoPublish flag must be set for ‘publishControl’ to have an effect.
publicationDate: (Deprecated in: release-2023-03)
Please use publishControl.lastPublicationDate. Sets the most recent publication date. The autoPublish flag must be set for this to have an effect.
content: (optional) An array of livingdocs components, must conform to your channel-config otherwise throws a validation error
design: (optional) An object with name and version. If no design is set it takes the design of the Project Config with the latest version
metadata: (optional) An object of metadata, must conform to your channel-config otherwise throws a validation error
translations: (optional) An object of translations
flags: (optional) define additional import logic:
- autoPublish: publishes imported documents immediately
- unpublish: unpublishes imported documents immediately
- onlyOverwriteUntouched: only update documents that have no manual changes in livingdocs
- neverOverwrite: never update documents through the import API

Example Request

{
  "systemName": "identifier-for-your-system",
  "webhook": "https://my-domain.com/webhooks/document-import",
  "context": {
    "myIdentifier": "some-identifier-sent-to-the-webhook"
  },
  "documents": [
    {
      "id": "123abc",
      "title": "test import",
      "contentType": "article",
      "checksum": "xyz456",
      "publishControl": {
        "firstPublicationDate": "1999-03-18T17:27:00.107Z",
        "significantPublicationDate": "1999-03-19T17:27:00.107Z",
        "lastPublicationDate": "1999-03-20T17:27:00.107Z",
      },
      "content": [
        {
          "identifier": "header",
          "content": {
            "catchline": "imported catchline",
            "title": "imported title",
            "author": "imported author"
          }
        }
      ],
      "design": {
        "name": "living-times",
        "version": "1.0.1"
      },
      "metadata": {
        "description": "foo"
      },
      "translations": [
        {
          "locale": "fr",
          "metadata": {
            "description": "foo FR"
          }
        }
      ],
      "flags": {
        "autoPublish": true
      }
    }
  ]
}

Response

200
OK
api/v1/import/documents
{
  "id": "25bzj8j"
}

Check Import Status for Documents

Required scope: public-api:write

Description

You can use this endpoint to check for the status and/or result of a document import.
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/v1/import/documents/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET api/v1/import/documents/status

Parameters

NameTypeRequiredNotes
?idstringxThe id that Livingdocs provided you for your prior call to “/import/documents”

Response

200
OK
api/v1/import/documents/status?id=25bzj8j
{
  "finished": true,
  "state": "success",
  "id": "25bzj8j",
  "logs": [
    {
      "system_name": "integration-tests",
      "external_id": "8Sv9Nu0d",
      "document_id": 1,
      "checksum": "123abc",
      "project_id": 3,
      "channel_id": 2,
      "revision_id": 1,
      "version": 1,
      "id": 1,
      "state": "imported"
    },
    {
      "state": "failed",
      "reason": "Invalid metadata",
      "external_id": "external-unique-id-345",
      "title": "my second document"
    }
  ]
}
200
OK
api/v1/import/documents/status?id=243kdc
{
  "finished": false,
  "state": "started",
  "id": "243kdc",
  "startedAt": "2020-01-01 13:45:12"
}
200
OK
api/v1/import/documents/status?id=098shjhv9
{
  "finished": true,
  "state": "failed",
  "id": "098shjhv9"
}
200
OK
api/v1/import/documents/status?id=098shjhv9
{
  "finished": false,
  "state": "lost",
  "id": "no import job found for id \"098shjhv9\""
}