Monax API (v1)

Download OpenAPI specification:Download

Happy Contracting!

Getting Started

We are pleased you have joined the Marmot-y movement.

Authentication

bearer

Security scheme type: API Key
Cookie parameter name: local_platform_access_token

external

Security scheme type: HTTP
HTTP Authorization Scheme bearer

Agreements

List agreements.

Returns information about agreements that:

  • are owned by the authenticated user,
  • are owned by an organization + department(s) to which the authenticated user belongs,
  • include the authenticated user in its signatories, or
  • include an organization + department(s) to which the authenticated user belongs in its signatories
Authorizations:

Responses

200

agreements retrieved

Response Schema: application/json
Array
isPrivate
boolean

Whether the encryption framework of the agreement is operational or not

address
string

Agreement's address on the blockchain

archetypeName
string

Human readable name of the archetype

attachmentsFileReference
string

Unique reference to the file wrapping up all of the attachments

createdAt
number

Unix timestamp object creation

creator
string

The entity who originally created the agreement

creatorDisplayName
string

Human readable name of the creator of the agreement

archetype
string

Address of the parent of the agreement

legalState
integer
Enum: 1 2 3 4 5

Every agreement contains a state machine which can only go one way through it's life-cycle. This state machine is very helpful for understanding at a "macro" level where are we within the contract's life-cycle.

This state machine is controlled by logic which exists on the blockchain and as such is very reliable and visible to all of the parties to the agreement (assuming they have the correct address of the contract).

The state machine encompasses the following states:

  • Legal State: 1 -> Formulation
  • Legal State: 2 -> Execution
  • Legal State: 3 -> Fulfilled
  • Legal State: 4 -> Cancelled
  • Legal State: 5 -> Defaulted
maxNumberOfAttachments
integer [ 0 .. 0 ]

(Currently not used) The maximum number of attachments which may be placed onto an agreement

name
string <= 32 characters

Human readable name of the agreement. Note that this field is limited to a maximum of 32 ASCII characters.

owner
string

The entity who controls the visibility of the agreement

ownerDisplayName
string

Human readable name of the owner of the agreement

tags
Array of objects (AgreementTag)
default

unexpected error

get /agreements

Monax's API's environments

https://{environment}api.monax.io{version}/agreements

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create an agreement.

Create an agreement with the fields and data that are included in the body of the request.

Authorizations:
Request Body schema: application/json
archetype
string

Address of the parent of the agreement

createdAt
number

Unix timestamp object creation

governingAgreements
Array of objects (AgreementGoverning)

An array of any agreements which are "parents" and as such "govern" the agreement in question. This array is not returned as a hierarchical order. Any entries in this array will be deemed as parents. For more information see here.

name
string <= 32 characters

Human readable name of the agreement. Note that this field is limited to a maximum of 32 ASCII characters.

owner
string

The entity who controls the visibility of the agreement

parameters
Array of objects (AgreementParameter)

An array of objects with each parameter's name, value, and data type. See the AgreementParameter object definition for more information on the data types. Note - If a parameter with type 8 (Signing Party) is given, the corresponding value will be added to the agreement's parties.

Responses

200

agreement created

Response Schema: application/json
address
string

Agreement's address on the blockchain

newUsers
Array of objects

New users that have been created in line with the creation of this agreement.

parameters
Array of objects (AgreementParameter)

An array of objects with each parameter's name, value, and data type. See the AgreementParameter object definition for more information on the data types. Note - If a parameter with type 8 (Signing Party) is given, the corresponding value will be added to the agreement's parties.

processInstance
string

Address of the agreement's formation process instance

default

unexpected error

post /agreements

Monax's API's environments

https://{environment}api.monax.io{version}/agreements

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "archetype": "string",
  • "name": "string",
  • "createdAt": 0,
  • "owner": "string",
  • "parameters":
    [
    ],
  • "governingAgreements":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "summary": "An example agreement creation response",
  • "value":
    {
    }
}

Retrieve an agreement.

Agreement information for a single agreement

Notes:

  • If the password provided is incorrect or a hoard reference which does not exist was passed to the posted Agreement this get will return a 401.
  • If the agreement was not authored by the logged in user or one of their organizations, or if its signatories does not include the logged in user or one of their organizations, this will return a 404.
Authorizations:
path Parameters
address
required
string
Example: 16830871DE9CD69AEBB9920ABA59E88B9923B324

Address of the agreement requesting

Responses

200

agreement retrieved

Response Schema: application/json
isAssignedTask
boolean

Understand if the entity retrieving the information has a currently pending task to be completed

activityInstances
Array of objects (AgreementActivityInstance)

An array of the currently pending activities which are attached to the agreement and controlled by it's process model

archetype
string

Address of the parent of the agreement

attachmentsFileReference
string

Unique reference to the file wrapping up all of the attachments

collectionId
string

If the agreement is part of a collection, the unique identifier of that collection is returned here

createdAt
number

Unix timestamp object creation

creator
string

The entity who originally created the agreement

creatorDisplayName
string

Human readable name of the creator of the agreement

documents
Array of objects (AgreementDocument)

Array of the prose template documents that provide the basis for the human-readable (traditional) contract.

N.B. these documents when displayed for a user are "assembled" in that they are ran through our documentary assembly processing system before they are displayed to the user in our webApp. This field only returns the "raw" document which needs to be ran through the Monax assembler if one wants to have the "full" contract equivalent to what is displayed in the webApp.

executionProcessDefinition
string

Address of the agreement's execution process definition

executionProcessInstance
string

Address of the agreement's execution process instance

formationProcessDefinition
string

Address of the agreement's formation process definition

formationProcessInstance
string

Address of the agreement's formation process instance

governingAgreements
Array of objects (AgreementGoverning)

An array of any agreements which are "parents" and as such "govern" the agreement in question. This array is not returned as a hierarchical order. Any entries in this array will be deemed as parents. For more information see here.

address
string

Agreement's address on the blockchain

isCreator
boolean

Understand if the entity retrieving the information is also the creator of the agreement

isParty
boolean

Understand if the entity retrieving the information is a legal party to the agreement

isPrivate
boolean

Whether the encryption framework of the agreement is operational or not

legalState
integer
Enum: 1 2 3 4 5

Every agreement contains a state machine which can only go one way through it's life-cycle. This state machine is very helpful for understanding at a "macro" level where are we within the contract's life-cycle.

This state machine is controlled by logic which exists on the blockchain and as such is very reliable and visible to all of the parties to the agreement (assuming they have the correct address of the contract).

The state machine encompasses the following states:

  • Legal State: 1 -> Formulation
  • Legal State: 2 -> Execution
  • Legal State: 3 -> Fulfilled
  • Legal State: 4 -> Cancelled
  • Legal State: 5 -> Defaulted
maxNumberOfAttachments
integer [ 0 .. 0 ]

(Currently not used) The maximum number of attachments which may be placed onto an agreement

name
string <= 32 characters

Human readable name of the agreement. Note that this field is limited to a maximum of 32 ASCII characters.

owner
string

The entity who controls the visibility of the agreement

ownerDisplayName
string

Human readable name of the owner of the agreement

parameters
Array of objects (AgreementParameter)

An array of objects with each parameter's name, value, and data type. See the AgreementParameter object definition for more information on the data types. Note - If a parameter with type 8 (Signing Party) is given, the corresponding value will be added to the agreement's parties.

parties
Array of objects (AgreementParty)

An array of objects with each party member's address, user id or organization name, signature timestamp, and address of the user that has signed for the party

privateParametersFileReference
string

Unique reference to the file wrapping all of the parameters which are not used by process models, and therefore not put onto the blockchain underlying Monax

processes
Array of objects (AgreementProcess)

An array of the processes which are attached to the agreement

signaturesFileReference
string

Unique reference to the file wrapping all of the data surrounding the signatures placed onto the agreement by the parties

default

unexpected error

get /agreements/{address}

Monax's API's environments

https://{environment}api.monax.io{version}/agreements/{address}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "$ref": "#/components/examples/Agreement"
}

Update an agreement.

Update information on a single agreement. Only the fields noted below may be updated once an agreement is created within the Agreements Network blockchain (this is by design of the protocol).

  • Tags
Authorizations:
path Parameters
address
required
string
Example: 16830871DE9CD69AEBB9920ABA59E88B9923B324

Address of the agreement requesting

Request Body schema: application/json
tags
Array of integers

Array of tags that should be applied to the agreement

Responses

200

agreement updated

default

unexpected error

put /agreements/{address}

Monax's API's environments

https://{environment}api.monax.io{version}/agreements/{address}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "statusCode": 400,
  • "error": "Bad Request",
  • "message": "Invalid parameter in query"
}

Retrieve attachments for an agreement.

Get all of the attachments that have been populated into an agreement's data room.

Authorizations:
path Parameters
address
required
string
Example: 16830871DE9CD69AEBB9920ABA59E88B9923B324

Address of the agreement requesting

Responses

200

attachments retrieved

Response Schema: application/json
Array
content
string

If the attachment was uploaded via a JSON Post in plain text rather than as a file upload, then the content will be the actual content of what was sent in.

If the attachment was uploaded via a multipart form upload as a file then the reference to the file will be provided here.

contentType
string
Enum: "fileReference" "plaintext"

The type of the content.

displayName
string

Human readable name of the submitter

name
string

The name of the attachment

submitter
string

Blockchain based address of the identity of the entity who uploaded to the attachment to the agreement's data room.

timestamp
integer

Unix timestamp of when the attachment was uploaded

default

unexpected error

get /agreements/{address}/attachments

Monax's API's environments

https://{environment}api.monax.io{version}/agreements/{address}/attachments

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Add attachment to agreement.

Add an attachment to the specific agreement. When requested with Content-Type: multipart/form-data, the attached file will be uploaded to Monax's content addressable, envelope encrypted storage system. The attachment's content will be set to unique reference for the file, and the name will be set to the file's name. When requested with Content-Type: application/json, the name and content from the request will be used as the attachment.

Authorizations:
path Parameters
address
required
string
Example: 16830871DE9CD69AEBB9920ABA59E88B9923B324

Address of the agreement requesting

Request Body schema:
content
string
name
string

Responses

200

attachment added to agreement

Response Schema: application/json
attachments
Array of objects (AgreementAttachmentDetail)

The updated array of attachments

attachmentsFileReference
string

Unique reference to the file wrapping up all of the attachments

default

unexpected error

post /agreements/{address}/attachments

Monax's API's environments

https://{environment}api.monax.io{version}/agreements/{address}/attachments

Request samples

Content type
Copy
Expand all Collapse all
{
  • "value":
    {
    }
  • </