Developer API

The Articheck API allows external systems and software to send report and artifact data into Articheck programatically.

Note: Version 1 of the API is now deprecated. We recommend every existing implementation to switch to version 2 of the API (below).

 

Authentication

The API uses bearer tokens for authentication of all endpoints.

Prompt a user to login with their email address and password. The API will exchange these credentials for a token.

POST https://api.articheck.com/v2/auth-token/

Request

 {
     "username":  "email@email.com",
     "password": "12345"
 }

Response

 {
     "token": "affb305ae401117ff33392f6ccd634676e72f1ae"
 }

Use the token in every request using headers:

Authentication: Bearer affb305ae401117ff33392f6ccd634676e72f1ae

 

Upload an artifact

POST https://api.articheck.com/v2/reports/

  • id string required – the object ID from your external system
  • artifact_id int
  • title string required
  • media_template string required (see list of available values below)
  • artist string
  • alt_id string
  • alt_id2 string
  • date_of_creation string
  • dimensions string – 24 x 5.716 x 10 always in centimetres (height x width x depth). Use a decimal separator; commas like in 24,5 are not currently supported.
  • frame_dimensions string (like dimensions)
  • packed_dimensions string (like dimensions)
  • dimensions_notes string
  • groups list (see below)
  • general_conditions_category string
  • general_conditions_notes string
  • examination_location string
  • examined_by string
  • examiner_title string
  • lender string
  • image string – base64-encoded image (Note: images are never shown in the response)

Notes

  • All non-required string values can be left out of the request entirely or be an empty string (neither will be present in the update).

Example request

 {
     "id": "819",
     "title": "Testing public API",
     "media_template": "painting",
     "dimensions": "30 x 5 x 20",
     "examination_location": "Here",
     "examined_by": "Dan"
 }

Example response

{
     "id": "819",
     "report_id": 5437,
     "artifact_id": 5427,
     "updated_at": "1565699519",
     "updated_by": "dan@articheck.com",
     "created_at": "1565699519",
     "title": "Testing public API",
     "artist": "Unknown artist",
     "alt_id": null,
     "alt_id2": null,
     "alt_id3": "",
     "media": null,
     "date_of_creation": null,
     "groups": [],
     "dimensions": "30 x 5 x 20",
     "general_conditions_category": "",
     "general_conditions_notes": "Alright but a bit worse for wear.",
     "examination_location": "Here",
     "examined_by": "Dan",
     "examiner_title": "",
     "media_template": "Painting - Standard"
 }

Updating artifacts

If you need to update artifact data in Articheck, send data to the same endpoint as above and include either an artifact_id or id.

  • If artifact_id is used and matches an existing artifact in Articheck, a new report will be added to that artifact, merging all existing values plus those in the request.
  • If id (the ID from your external system) is used and artifact_id is not, the system will attempt to find an artifact with the same ID. A new report version of that artifact will be add if there is ONE matching artifact.

 

Adding to groups

groups should be a JSON list of objects. Reports will be added to every group listed in groups. Reports cannot currently be removed from groups over the API.

Groups will be added or updated within Articheck based on the code value you provide. If the code is already in use in Articheck, the group will be updated with any details sent in the request.

  • code string required
  • type string – empty string (defaults to general), general or exhibition
  • name string
  • description string

Exhibition groups have these extra fields:

  • start date required (YYYY-MM-DD format)
  • end date required (YYYY-MM-DD format)
  • venues string required

Example response

 {
   "examiner_title": "", 
   "general_conditions_category": "", 
   "updated_at": "1565790890", 
   "date_of_creation": null, 
   "alt_id": null, 
   "general_conditions_notes": "", 
   "media_template": "Painting - Standard", 
   "alt_id2": null, 
   "dimensions": null, 
   "title": "Testing report upload", 
   "media": null, 
   "updated_by": "test2@articheck.com", 
   "id": "71917", 
   "report_id": 18, 
   "artifact_id": 18, 
   "examination_location": "", 
   "groups": [
     {
       "code": "7", 
       "end": "2019-08-31", 
       "description": "Some description.", 
       "venues": "A location", 
       "start": "2019-07-01", 
       "type": "exhibition", 
       "id": 8, 
       "name": "New name"
     }
   ], 
   "alt_id3": "", 
   "artist": null, 
   "created_at": "1565790890",
   "examined_by": ""
 }

 

Media template values

Articheck has a defined list of templates that can be used to expose different fields in the condition report forms.

Whenever a report is added to Articheck over the API, a media template must be chosen (use an ID from below).

“Artwork / Object – Basic” artwork-object-basic
“Painting – Basic” painting-basic
“Painting – Standard” painting-standard
“Painting – Detailed” painting-detailed
“Paper – Basic” paper-basic
“Paper – Standard” paper-standard
“Paper – Detailed” paper-detailed
“Sculpture – Basic” sculpture-basic
“Sculpture – Standard” sculpture-standard
“Sculpture – Detailed” sculpture-detailed
“Object – Basic” object-basic
“Object – Standard” object-standard
“Object – Detailed” object-detailed
“Antique – Basic” antique-basic
“Antique – Detailed” antique-detailed
“Antique – Standard” antique-standard
“Inventory Item” inventory-item
“Textile – Detailed” textile-detailed
“Books, Manuscripts and Bound Materials” books
“Photograph” photograph