Documents

Import Documents

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.
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X POST "https://edit.livingdocs.io/proxy/api/api/v1/import/documents" \
  -H "Accept: application/json" \
  -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

NameTypeRquiredNotes
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
publicationDate: sets the date of a publication. ‘autoPublish’ flag must be set for this to have an effect.
livingdoc: A valid livingdoc declaration (content / design), must conform to your channel-config otherwise throws a validation error
metadata: An object of metadata, must conform to your channel-config otherwise throws a validation error
flags: (optional) define additional import logic:
‘autoPublish’: publishes 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",
      "publicationDate": "1999-03-18T17:27:00.107Z",
      "livingdoc": {
        "content": [
          {
            "identifier": "header",
            "content": {
              "catchline": "imported catchline",
              "title": "imported title",
              "author": "imported author"
            }
          }
        ],
        "design": {
          "name": "living-times",
          "version": "1.0.1"
        }
      },
      "metadata": {
        "description": "foo"
      },
      "flags": {
        "autoPublish": true
      }
    }
  ]
}

Response

200
OK
api/v1/import/documents
{
  "id": "25bzj8j"
}
429
Usage Limit Exceeded
api/v1/import/documents
[
  {
    "status": 429,
    "error": "Usage Limit Exceeded",
    "error_details": {
      "message": "Your plan does not allow you to upload more than 100 per day.\n      You already uploaded 99 in the last 24 hours and are trying to upload 10 more.\n      Please try again later."
    }
  }
]

Check Import Status for Documents

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://edit.livingdocs.io/proxy/api/api/v1/import/documents/status" \
  -H "Accept: application/json" \
  -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\""
}