Images

Import Images

Required scope: public-api:write

Description

The image import creates image entries in the Media Library and upload the image asset to the configured blob storage. The image import in Livingdocs is asynchronous. You post a batch of images that you want to import and get back a jobId that you can use to retrieve the import job state.

You can patch existing media library entries with the patch endpoint.

Use Cases

Initial import from a legacy system - When doing an initial import one usually first imports all images and then imports documents referencing the images.

Curl Example

ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/v1/import/images" \
  -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/image-import",
    "images": [
      {
        "url": "https://placekitten.com/800/600",
        "id": "123abc",
        "fileName": "cat",
        "metadata": {
          "caption": "foo"
        }
      }
    ]
  }
  EOF

Endpoint

POST /api/v1/import/images

Parameters

Name	Type	Required	Notes
systemName	string	x	Identifier for the system you are importing from, e.g. an archive
webhook	uri		Endpoint 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.
context	object		An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.
images	array	x	An array of images to import. Each entry is an object with the following keys, all of which are required: url: a URL to an image file, no data urls allowed, allowed types: png, jpg, gif, svg id: a unique id (stored as externalId in Livingdocs) that identifies the image on your end, must be unique within your project fileName: the title that the image should get in livingdocs metadata: An object of metadata according to your project config mediaType: The handle of one of the mediaTypes from your project configuration

Example Request

{
  "systemName": "identifier-for-your-system",
  "webhook": "https://my-domain.com/webhooks/image-import",
  "context": {
    "myIdentifier": "some-identifier-sent-to-the-webhook"
  },
  "images": [
    {
      "url": "https://placekitten.com/800/600",
      "id": "123abc",
      "fileName": "cat",
      "metadata": {
        "caption": "foo"
      }
    }
  ]
}

Response

200

/api/v1/import/images

{
  "id": "25bzj8j"
}

Check Import Status for Images

Required scope: public-api:write

Description

API endpoints for importing and checking status of image imports.

Curl Example

ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/v1/import/images/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET /api/v1/import/images/status

Parameters

Name	Type	Required	Notes
id	string	x	The id that Livingdocs provided you for your prior call to ‘/import/images’

Response

200

/api/v1/import/images/status?id=25bzj8j

{
  "finished": true,
  "state": "success",
  "id": "25bzj8j",
  "images": [
    {
      "status": "success",
      "externalId": "external-unique-id-123",
      "title": "my image",
      "image": {
        "mediaId": "jjiwhsf23kdk",
        "originalUrl": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg",
        "url": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format",
        "width": 100,
        "height": 100,
        "mimeType": "image/png",
        "imageService": "imgix"
      }
    },
    {
      "status": "skipped",
      "reason": "already exists",
      "externalId": "external-unique-id-234",
      "title": "my second image",
      "image": {
        "mediaId": "jjiwhsf23wer",
        "originalUrl": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format",
        "url": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format",
        "width": 100,
        "height": 100,
        "mimeType": "image/png",
        "imageService": "imgix"
      }
    },
    {
      "status": "failed",
      "reason": "Could not upload image",
      "externalId": "external-unique-id-345",
      "title": "my third image"
    }
  ]
}

200

/api/v1/import/images/status?id=243kdc

{
  "finished": false,
  "state": "started",
  "id": "243kdc",
  "startedAt": "2020-01-01 13:45:12"
}

200

/api/v1/import/images/status?id=098shjhv9

{
  "finished": true,
  "state": "failed",
  "id": "098shjhv9"
}