Verisart API v0.2

What’s New?

Last updated: April 19 2018 by H. Q. Phan

The Verisart API now can do the following:

  • Allows users to download a PDF snapshot of the certificate.

Previous features in the March 26 update include:

  • Set custom external ID for each artist.
  • Query Verisart Artist ID by external ID.
  • Set custom key-value data for each artwork, which can be used to set custom object type and external ID.
  • Query Verisart Object ID by external ID.
  • Assign multiple image URLs to an artwork and set one of them as the main image.

Previous features in the March 16 update include:

  • Request for Access Tokens with client credentials and partner account.
  • Refresh Access Token.
  • Create new artist profiles with name, email, signature images and link them to your partner account. You will be able to see a list of artist profiles on samo.versiart.com.
  • Query artist’s Verisart ID by email.
  • Create Certificate of Authenticity with custom background and icon.
  • Query the current status of the certificates (processing, stamped or confirmed).

Overview

Verisart API enables partners to easily integrate existing infrastructures with Verisart’s blockchain based art provenance platform. Thus, complex implementation details such as CIDOC-CRM and cryptographic protocols are hidden behind self-explaining, task-oriented API calls. To start testing Verisar API, users only need: - A Verisart partner account, which comes with an username, a password and an unique partner ID. - Client credentials for machine-machine communication. - A command line tool such as cURL, which is pre-installed on MacOS and Linux.

To integrate Verisart API with existing applications, one needs to implement the data structures and exchange protocols explained in this document. Verisart provides a reference implementation written in Golang on github. Please contact us if you want to download the SDK.

For testing purposes, we host a staging version of Verisart API at samo.verisart.com.

(1) CONVENTIONS

  • We use a pair of <> brackets to specify a placeholder for the actual value.
  • ... is used to indicate a common field explained in this section.
  • Data type of each field is assumed to be a string if unspecified.

(1.1) SETTING ACCESS TOKEN AND CONTENT TYPE

Access tokens must be used in all request headers, except for when requesting for the token itself (Section 2). Request header has the following format:

REQUEST HEADERS

Common fields in a request header are:

Host: samo.verisart.com
Accept: */*
Authorization: Bearer <accessToken>
Content-Length: <contentLength>
Content-Type: <contentType>
  1. accessToken: Access token obtained in Section 2 and Section 3.
  2. contentType: Body format. Both application/json and application/x-www-form-urlencoded are accepted.

(1.2) COMMON JSON FIELDS

  1. artistID: Verisart Artist ID (UUIDv4).
  2. artistIRI: Verisart Artist IRI. For example: http://verisart.com/id/actor/<artistID>
  3. extID: External ID, can be used to store partner’s self-referencing ID.
  4. objectID: Verisart Object ID (UUIDv4).
  5. objectURL: A link to view an object.
  6. objectIRI: Verisart Object IRI. For example: http://verisart.com/id/object/<objectID>
  7. partnerID: Verisart Partner ID (UUIDv4).

(2) REQUEST FOR A NEW TOKEN

Verisart uses OAuth2’s Client Credentials for machine-machine communication. You will need both client credentials and partner’s account to create artwork certificate and artist profiles.

URL

http://samo.verisart.com/oauth2/token

REQUEST HEADER

base64encodedCredentials is a Base-64 encoded string of format <clientID>:<password>.

POST /oauth2/token HTTP/1.1
Host: samo.verisart.com
Authorization: Basic <base64encodedCredentials>
User-Agent: <userAgent>
Accept: */*
Content-Type: application/x-www-form-urlencoded
Content-Length: 63

REQUEST BODY

grant_type=password&username=<userName>&password=<password>
  1. userName: Patner’s username.
  2. password: Partner’s password.

RESPONSE BODY

  1. access_token: Access token.
  2. expires_in: Expirity.
  3. refresh_token: Refresh token.
  4. token_type: Always Bearer

EXAMPLE

curl -v -d "grant_type=password&username=<userName>&password=<password>" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://<clientID>:<clientPassword>@samo.verisart.com/oauth2/token

(3) REFRESH ACCESS TOKEN

This is used for requesting new access token.

URL

http://samo.verisart.com/oauth2/token

REQUEST HEADER

POST /oauth2/token HTTP/1.1
Host: samo.verisart.com
Authorization: Basic <base64EncodedCredentials>
User-Agent: <userAgent>
Accept: */*
Content-Type: application/x-www-form-urlencoded
Content-Length: 61
  1. base64EncodedCredentials: See Section 2.

REQUEST BODY

grant_type=refresh_token&refresh_token=<refreshToken>
  1. refreshToken: Refresh token obtained in Section 2.

RESPONSE BODY

  1. access_token: Access token.
  2. expires_in: Expirity.
  3. refresh_token: Refresh token.
  4. token_type: Always Bearer.

EXAMPLE

curl -v -d "grant_type=refresh_token&refresh_token=Mj_nCSWEQsyTOYRJjKjMXA" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://<clientID>:<clientPassword>@samo.verisart.com/oauth2/token

(4) CREATE A NEW ARTIST

NOTE: You now need your Partner ID to create new artists and certificates

URL

http://samo.verisart.com/api/v1/partner/<partnerID>/statements/artist
  • partnerID: …

REQUEST HEADER

POST /api/v1/partner/<partnerID>/statements/artist HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessToken>
Content-Length: <contentLength>
Content-Type: <contentType>
  1. partnerID: …
  2. accessToken: …
  3. cotentType: …

REQUEST BODY

  1. name (Required): Name of the artist
  2. email (Optional): Email address. If specified, a Verisart account will be created for this artist.
  3. extID (Optional): External artist ID. Can be used to identify an artist by partner.
  4. signatureURL (Optional): URL to an signature image.
  5. role (Required): The role of current partner. Must have the following values
    • "self"
    • "gallery"
    • "fabricator"
    • "retailer"
    • "studio"

RESPONSE BODY

  1. name: Name of the artist.
  2. email: Email address. Empty if no user account associated with this artist.
  3. id: Unique Verisart Artist ID (artistID).
  4. iri: Unique Verisart Artist IRI (artistIRI).
  5. extID: External artist ID.

EXAMPLE

curl -v -d "@test_artist_stmt.json" -H "Authorization: Bearer ux515TMgRFKLgT68daemqg" "http://samo.verisart.com/api/v1/partner/<partnerID>/statements/artist"

(5) QUERY ARTIST BY EXTERNAL ARTIST ID

The ID (or IRI) is used to identify artist in Verisart DB.

URL

http://samo.verisart.com/api/v1/partner/<partnerID>/artist/by-ext-id/<extID>
  1. partnerID: …
  2. extID: External artist ID.

REQUEST HEADER

GET /api/v1/partner/<partnerID>/artist/by-ext-id/<extID> HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessCode>
  1. partnerID: …
  2. extID: External artist ID.
  3. accessCode: …

RESPONSE BODY

Response body can contain 0 or more result(s) with fields:

  1. name: Name of the artist.
  2. email: Email address. Empty if no user account associated with this artist.
  3. id: Unique Verisart Artist ID (artistID).
  4. iri: Unique Verisart Artist IRI (artistIRI).
  5. extID: External artist ID.

EXAMPLE

curl -v -H "Authorization: Bearer ephkGbM0Re6gKbITe7iQ8A" "http://samo.verisart.com/api/v1/partner/<partnerID>/artists/by-ext-id/ARTIST-001"

(6) CREATE A CERTIFICATE FOR AN ARTWORK

URL

http://samo.verisart.com/api/v1/partner/<partnerID>/statements/artwork
  1. partnerID: …

REQUEST HEADER

POST /api/v1/partner/<partnerID>/statements/artwork HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessToken>
Content-Length: <contentLength>
Content-Type: <contentType>
  1. partnerID: …
  2. accessToken: …
  3. cotentType: …

REQUEST BODY

  1. statements: A list of artwork statements (certificates), each has format:
    1. objectType (Required): The type of artwork. Must have the following values:
      • "painting"
      • "sculpture"
      • "print"
      • "picture"
      • "design"
      • "collectible"
      • "photo"
      • "drawing"
      • "mixed media"
      • "furniture"
      • "book"
      • "ephemera"
    2. extID (Optional): …
    3. artistIRI (Required): Must be a valid Verisart’s IRI
    4. title (Required): Artwork title.
    5. year (Required): Production year.
    6. medium (Required): Artwork’s material. Can be an arbitrary string.
    7. width (Required): The width of this artwork.
    8. height (Required): The height of this artwork.
    9. depth (Optional): The depth of this artwork.
    10. unit (Required): Unit for width, height and depth. Must be one of:
      • "cm"
      • "inches"
    11. inventoryNumber (Optional): Inventory number is used to identify this artwork. Can be an arbitrary string.
    12. imageURLs (Required): A list of json objects with fields:
      1. type (Required): The type of this image. Must be one of:
        • "front": Front image (primary image). At least one front image is required.
        • "back": Back image.
        • "undefined: Undefined.
        • "related-document": Other documents like receipt, invoice etc.
      2. "url" (Required): Image url.
    13. edition (Optional): Edition number
    14. editionVolume (Conditional): Required if edition is specified.
    15. isAP (Optional): Whether this artwork is an Artist Proof (AP). Must be one of:
      • "yes": Yes
      • "no": No
    16. apVolume (Optional): AP volume.
    17. issuerNote (Optional): Issuer’s note.
    18. privacyPref (Required): Must be one of:
      • "private": Private
      • "public": Public
    19. data (Optional): Arbitrary json object with string values only. Can be used to store other external data.

RESPONSE BODY

Success

Error

  1. certs: can be null or A list of json objects
    1. objectID: Verisart Object ID.
    2. extID: …
    3. objectURL: Unique URL to view this artwork online.
    4. artistIRI: Verisart Artist IRI.
    5. title: …
    6. inventoryNumber: …
  2. errors: can be null or json objects:
    1. byRow: json object that organizes errors by the index of statement. Each error object has format:
      1. domain: Where the error happens.
      2. code: Verisart custom error code.
      3. message: Error message.
      4. field: The erroneous field.
    2. error: A single error message.

EXAMPLE

curl -v -d "@test_artwork_stmt.json" -H "Authorization: Bearer l94Qe1fWQJK-juwvlJ-7RA" "http://samo.verisart.com/api/v1/partner/<partnerID>/statements/artwork"

(7) QUERY ARTWORK BY EXTERNAL ARTWORK ID

URL

http://samo.verisart.com/api/v1/partner/<partnerID>/artworks/by-ext-id/<extID>
  1. partnerID: …
  2. extID: External artwork ID.

REQUEST HEADER

POST /api/v1/partner/<partnerID>/artworks/by-ext-id/<extID> HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessToken>
Content-Length: <contentLength>
Content-Type: <contentType>
  1. partnerID: …
  2. extID: External artwork ID.
  3. accessToken: …
  4. cotentType: …

RESPONSE BODY

  1. objectID: …
  2. extID: External artwork ID.
  3. objectURL: …
  4. title: Empty. Reserved for future use.

EXAMPLE

curl -v -H "Authorization: Bearer ephkGbM0Re6gKbITe7iQ8A" "http://samo.verisart.com/api/v1/partner/<partnerID>/artworks/by-ext-id/ARTWORK-001"

(8) FIND AN ARTWORK BY KEY-VALUE PAIR

This method provides a way for partner to attach arbitrary key-value data to an object. The data won’t go into CIDOC graph statements.

URL

http://samo.verisart.com/api/v1/partner/<partnerID>/artworks/by-key-value/<key>/<value>
  1. partnerID: …
  2. key: Search key.
  3. value: Search value.

REQUEST HEADER

GET /api/v1/partner/<partnerID>/artworks/by-key-value/<key>/<value> HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessToken>
  1. partnerID: …
  2. key: …
  3. value: …
  4. accessToken: …

RESPONSE BODY

  1. objectID: …
  2. objectURL: …
  3. key: Search key.
  4. value: Search value.
  5. title: Empty. Reserved for future use.

EXAMPLE

curl -v -H "Authorization: Bearer ephkGbM0Re6gKbITe7iQ8A" "http://samo.verisart.com/api/v1/partner/<partnerID>/artworks/by-key-value/extID/ARTWORK-001"

(9) CHECK STATUS OF AN ARTWORK

Check whether the certificate for an artwork has been confirmed on the blockchain.

URL

http://samo.verisart.com/api/v1/objects/<objectID>/status
  1. objectID: …

REQUEST HEADER

GET /api/v1/objects/<objectID>/status HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessToken>
  1. objectID: …
  2. accessToken: …

RESPONSE BODY

The response body is rather verbose for now but the info might become handy in the future as it allows partners to independently verify cryptographic proof of a statement against the blockchain(s). Statements about an artwork are organized by “Commit”, similar to the way version control systems manage code. Each commit corresponds to a version of the certificate.

Key output values:

  • commits -> createdAt: If not empty, indicates the time when the statement was created. If this is empty, the satement is still being processed by Verisart.
  • commits -> stampedAt: If not empty, indicates the time the statement was submitted to Bitcoin blockchain.
  • commits -> completedAt: If not empty, indicates the time the statement was confirmed on the Bitcoin blockchain.

IMPORTANT NOTE: Partner should not pass objectURL to user if completedAt is empty as it is still pending to be time-stamped on the blockchain.

EXAMPLE

curl -v -H "Authorization: Bearer l94Qe1fWQJK-juwvlJ-7RA" "http://samo.verisart.com/api/v1/objects/c61a0e77-426e-428f-8dd2-2231b6bc0f5f/status"

(10) QUERY PDF SNAPSHOTS

Check availability of PDF snapshots for a certificate

URL

http://samo.verisart.com/api/v1/objects/<objectID>/pdf
  1. objectID: …

REQUEST HEADER

GET /api/v1/objects/<objectID>/pdf HTTP/1.1
Host: samo.verisart.com
User-Agent: <userAgent>
Accept: */*
Authorization: Bearer <accessToken>
  1. objectID: …
  2. accessToken: …

RESPONSE BODY

  1. objectID: …
  2. createdAt: The time when this certificate was created.
  3. stampedAt: The time when this certificate was sent out for time-stamping. Is empty if artwork is still being processed.
  4. completedAt: The time when this certificate was confirmed on the blockchain. Is empty if timestamp hasn’t been confirmed.
  5. pdfURL: Downloadable link for the PDF.
  6. status: Current status of this certificate. Can be one of: processing, stamped or confirmed.

EXAMPLE

curl -v -H "Authorization: Bearer p39_VQ5bRqCBFyNl_pCGhA" "http://samo.verisart.com/api/v1/objects/c61a0e77-426e-428f-8dd2-2231b6bc0f5f/pdf"

ENDS