Inventory API (v8.3)

http://localhost

Inventory API
/inventory

Inventory API

API for interacting with an inventory of physical resources

/inventory

GET /inventory/items

Retrieve a list of item items.

GET /inventory/items

Query Parameters

offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
```
0
```
limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response
Example:
```
10
```
query: (string)
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
using CQL (indexes for item and material type)
Example:
```
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode

barcode=="65345656554"
```
lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns a list of item items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of item records",
  "type": "object",
  "properties": {
    "items": {
      "description": "List of item records",
      "id": "items",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "item.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "items",
    "totalRecords"
  ]
}

Example:

{
  "items": [
    {
      "id": "43ec57e3-3974-4d05-a2c2-95126e087b72",
      "title": "Nod",
      "barcode": "456743454532",
      "status": {
        "name": "Available"
      },
      "materialType": {
        "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
        "name": "Book"
      },
      "permanentLocation": {
        "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
        "name": "Main Library"
      },
      "permanentLoanType": {
        "id": "11477028-d9e6-44d2-9364-5c6f51053f51",
        "name": "Reading Room"
      }
    },
    {
      "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
      "title": "Uprooted",
      "callNumber": "D11.J54 A3 2011",
      "barcode": "645398607547",
      "status": {
        "name": "Available"
      },
      "materialType": {
        "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
        "name": "Book"
      },
      "permanentLoanType": {
        "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
        "name": "Can Circulate"
      },
      "temporaryLoanType": {
        "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
        "name": "Course Reserve"
      },
      "permanentLocation": {
        "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
        "name": "Main Library"
      },
      "temporaryLocation": {
        "id": "0df935eb-f3f4-4741-9ac6-33c500174b96",
        "name": "Annex"
      }
    }
  ],
  "totalRecords": 2
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list items -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list items -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /inventory/items

Create a new item item.

POST /inventory/items

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An item record",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID"
    },
    "holdingsRecordId": {
      "description": "ID of the holding the item is a member of",
      "type": "string"
    },
    "formerIds": {
      "type": "array",
      "description": "Previous identifiers assigned to the item",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },    
    "title": {
      "type": "string",
      "description": "title of the item (read only, inherited from associated instance)",
      "readonly": true
    },
    "contributorNames": {
      "description": "A list of contributor names",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The contributor name",
            "type": "string"
          }
        }
      }
    },
    "callNumber": {
      "type": "string",
      "description": "call number (read only, inherited from associated holdings record)",
      "readonly": true
    },
    "barcode": {
      "type": "string"
    },
    "accessionNumber": {
      "type": "string",
      "description": "Also called inventar number"
    },

    "itemLevelCallNumber": {
      "type": "string"
    },
    "itemLevelCallNumberPrefix": {
      "type": "string"
    },
    "itemLevelCallNumberSuffix": {
      "type": "string"
    },
    "itemLevelCallNumberTypeId": {
      "type": "string"
    },
    "volume": {
      "type": "string"
    },
    "enumeration": {
      "type": "string"
    },
    "chronology": {
      "type": "string"
    },
    "yearCaption": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "itemIdentifier": {
      "type": "string"
    },
    "copyNumbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "numberOfPieces": {
      "type": "string"
    },
    "descriptionOfPieces": {
      "type": "string"
    },
    "numberOfMissingPieces": {
      "type": "string"
    },
    "missingPieces": {
      "type": "string"
    },
    "missingPiecesDate": {
      "type": "string"
    },
    "itemDamagedStatusId": {
      "type": "string"
    },
    "itemDamagedStatusDate": {
      "type": "string"
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNoteTypeId": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "staffOnly": {
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "circulationNotes": {
      "type": "array",
      "description": "Notes to be displayed in circulation processes",
      "items": {
        "type": "object",
        "properties": {
          "noteType": {
            "type": "string",
            "description": "Type of circulation process that the note applies to",
            "enum": ["Check in", "Check out"]
          },
          "note": {
            "type": "string",
            "description": "Text to display"
          },
          "staffOnly": {
            "type": "boolean",
            "default": "Flag to restrict display of this note",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "status": {
      "description": "The status of the item",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status e.g. Available, Checked out, In transit",
          "type": "string"
        },
        "date": {
          "description": "Date of a status",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "materialType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLoanType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLoanType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLocation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLocation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "effectiveLocation": {
       "type": "object",
       "description": "effective location of the item (read only, derived from locations on HoldingsRecord and Item)",
       "readonly": true,
       "properties": {
         "id": {
           "type": "string",
           "readonly": true
         },
         "name": {
           "type": "string",
           "readonly": true
         }
       }
    },
    "electronicAccess": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "purchaseOrderLineIdentifier": {
      "type": "string",
      "description": "ID referencing a remote purchase order object related to this item"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "materialType",
    "permanentLoanType"
  ]
}

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers

Location: required (string)
URI to the created item item

Body

Media type: application/json

Type: any

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add item -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create items -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

DELETE /inventory/items

DELETE /inventory/items

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 204

All items deleted

GET /inventory/items/{itemId}

Retrieve item item with given {itemId}

GET /inventory/items/{itemId}

URI Parameters

itemId: required (string)

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An item record",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID"
    },
    "holdingsRecordId": {
      "description": "ID of the holding the item is a member of",
      "type": "string"
    },
    "formerIds": {
      "type": "array",
      "description": "Previous identifiers assigned to the item",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },    
    "title": {
      "type": "string",
      "description": "title of the item (read only, inherited from associated instance)",
      "readonly": true
    },
    "contributorNames": {
      "description": "A list of contributor names",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The contributor name",
            "type": "string"
          }
        }
      }
    },
    "callNumber": {
      "type": "string",
      "description": "call number (read only, inherited from associated holdings record)",
      "readonly": true
    },
    "barcode": {
      "type": "string"
    },
    "accessionNumber": {
      "type": "string",
      "description": "Also called inventar number"
    },

    "itemLevelCallNumber": {
      "type": "string"
    },
    "itemLevelCallNumberPrefix": {
      "type": "string"
    },
    "itemLevelCallNumberSuffix": {
      "type": "string"
    },
    "itemLevelCallNumberTypeId": {
      "type": "string"
    },
    "volume": {
      "type": "string"
    },
    "enumeration": {
      "type": "string"
    },
    "chronology": {
      "type": "string"
    },
    "yearCaption": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "itemIdentifier": {
      "type": "string"
    },
    "copyNumbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "numberOfPieces": {
      "type": "string"
    },
    "descriptionOfPieces": {
      "type": "string"
    },
    "numberOfMissingPieces": {
      "type": "string"
    },
    "missingPieces": {
      "type": "string"
    },
    "missingPiecesDate": {
      "type": "string"
    },
    "itemDamagedStatusId": {
      "type": "string"
    },
    "itemDamagedStatusDate": {
      "type": "string"
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNoteTypeId": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "staffOnly": {
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "circulationNotes": {
      "type": "array",
      "description": "Notes to be displayed in circulation processes",
      "items": {
        "type": "object",
        "properties": {
          "noteType": {
            "type": "string",
            "description": "Type of circulation process that the note applies to",
            "enum": ["Check in", "Check out"]
          },
          "note": {
            "type": "string",
            "description": "Text to display"
          },
          "staffOnly": {
            "type": "boolean",
            "default": "Flag to restrict display of this note",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "status": {
      "description": "The status of the item",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status e.g. Available, Checked out, In transit",
          "type": "string"
        },
        "date": {
          "description": "Date of a status",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "materialType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLoanType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLoanType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLocation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLocation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "effectiveLocation": {
       "type": "object",
       "description": "effective location of the item (read only, derived from locations on HoldingsRecord and Item)",
       "readonly": true,
       "properties": {
         "id": {
           "type": "string",
           "readonly": true
         },
         "name": {
           "type": "string",
           "readonly": true
         }
       }
    },
    "electronicAccess": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "purchaseOrderLineIdentifier": {
      "type": "string",
      "description": "ID referencing a remote purchase order object related to this item"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "materialType",
    "permanentLoanType"
  ]
}

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"item not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /inventory/items/{itemId}

Delete item item with given {itemId}

DELETE /inventory/items/{itemId}

URI Parameters

itemId: required (string)

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete item -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"item not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /inventory/items/{itemId}

Update item item with given {itemId}

PUT /inventory/items/{itemId}

URI Parameters

itemId: required (string)

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An item record",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID"
    },
    "holdingsRecordId": {
      "description": "ID of the holding the item is a member of",
      "type": "string"
    },
    "formerIds": {
      "type": "array",
      "description": "Previous identifiers assigned to the item",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },    
    "title": {
      "type": "string",
      "description": "title of the item (read only, inherited from associated instance)",
      "readonly": true
    },
    "contributorNames": {
      "description": "A list of contributor names",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The contributor name",
            "type": "string"
          }
        }
      }
    },
    "callNumber": {
      "type": "string",
      "description": "call number (read only, inherited from associated holdings record)",
      "readonly": true
    },
    "barcode": {
      "type": "string"
    },
    "accessionNumber": {
      "type": "string",
      "description": "Also called inventar number"
    },

    "itemLevelCallNumber": {
      "type": "string"
    },
    "itemLevelCallNumberPrefix": {
      "type": "string"
    },
    "itemLevelCallNumberSuffix": {
      "type": "string"
    },
    "itemLevelCallNumberTypeId": {
      "type": "string"
    },
    "volume": {
      "type": "string"
    },
    "enumeration": {
      "type": "string"
    },
    "chronology": {
      "type": "string"
    },
    "yearCaption": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "itemIdentifier": {
      "type": "string"
    },
    "copyNumbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "numberOfPieces": {
      "type": "string"
    },
    "descriptionOfPieces": {
      "type": "string"
    },
    "numberOfMissingPieces": {
      "type": "string"
    },
    "missingPieces": {
      "type": "string"
    },
    "missingPiecesDate": {
      "type": "string"
    },
    "itemDamagedStatusId": {
      "type": "string"
    },
    "itemDamagedStatusDate": {
      "type": "string"
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNoteTypeId": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "staffOnly": {
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "circulationNotes": {
      "type": "array",
      "description": "Notes to be displayed in circulation processes",
      "items": {
        "type": "object",
        "properties": {
          "noteType": {
            "type": "string",
            "description": "Type of circulation process that the note applies to",
            "enum": ["Check in", "Check out"]
          },
          "note": {
            "type": "string",
            "description": "Text to display"
          },
          "staffOnly": {
            "type": "boolean",
            "default": "Flag to restrict display of this note",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "status": {
      "description": "The status of the item",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status e.g. Available, Checked out, In transit",
          "type": "string"
        },
        "date": {
          "description": "Date of a status",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "materialType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLoanType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLoanType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "permanentLocation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "temporaryLocation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "id"
      ]
    },
    "effectiveLocation": {
       "type": "object",
       "description": "effective location of the item (read only, derived from locations on HoldingsRecord and Item)",
       "readonly": true,
       "properties": {
         "id": {
           "type": "string",
           "readonly": true
         },
         "name": {
           "type": "string",
           "readonly": true
         }
       }
    },
    "electronicAccess": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "uniform resource identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "the value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "purchaseOrderLineIdentifier": {
      "type": "string",
      "description": "ID referencing a remote purchase order object related to this item"
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "materialType",
    "permanentLoanType"
  ]
}

Example:

{
  "id": "0b96a642-5e7f-452d-9cae-9cee66c9a892",
  "title": "Uprooted",
  "contributorNames": [{ "name": "Novik, Naomi" }],
  "callNumber": "D11.J54 A3 2011",
  "barcode": "645398607547",
  "status": {
    "name": "Available"
  },
  "materialType": {
    "id": "fcf3d3dc-b27f-4ce4-a530-542ea53cacb5",
    "name": "Book"
  },
  "permanentLoanType": {
    "id": "8e570d0d-931c-43d1-9ca1-221e693ea8d2",
    "name": "Can Circulate"
  },
  "temporaryLoanType": {
    "id": "74c25903-4019-4d8a-9360-5cb7761f44e5",
    "name": "Course Reserve"
  },
  "permanentLocation": {
    "id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
    "name": "Main Library"
  }
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update item -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"item not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /inventory/instances

Retrieve a list of instance items.

GET /inventory/instances

Query Parameters

offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
```
0
```
limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response
Example:
```
10
```
query: (string)
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
using CQL (indexes for item and material type)
Example:
```
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode

title="uproot*"
```
lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns a list of instance items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of instance records",
  "type": "object",
  "properties": {
    "instances": {
      "description": "List of instance records",
      "id": "instances",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "instance.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "instances",
    "totalRecords"
  ]
}

Example:

{
  "instances": [
    {
      "@context": "http://localhost:9130/inventory/instance/context",
      "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
      "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
      "source": "Local",
      "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
      "links": {
        "self": "http://localhost:9130/inventory/instance/cf23adf0-61ba-4887-bf82-956c4aae2260"
      },
      "identifiers": [
        {
          "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
          "value": "9781466636897"
        }
      ],
      "contributors": [
        {
          "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
          "name": "Samuels, Simon"
        }
      ]
    },
    {
      "@context": "http://localhost:9130/inventory/instance/context",
      "id": "ab312025-0642-45a6-8545-aa02aff1ae7c",
      "title": "ADVANCING RESEARCH METHODS WITH NEW TECHNOLOGIES.",
      "source": "Local",
      "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
      "links": {
        "self": "http://localhost:9130/inventory/instance/ab312025-0642-45a6-8545-aa02aff1ae7c"
      },
      "identifiers": [
        {
          "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
          "value": "9781466639195"
        }
      ],
      "contributors": [
        {
          "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
          "name": "Jules, Julian"
        }
      ]
    }
  ],
  "totalRecords": 2
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list instances -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list instances -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /inventory/instances

Create a new instance item.

POST /inventory/instances

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "type": "object",
  "properties": {
    "@context": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory;  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)"
    },
    "parentInstances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "superInstanceId": {
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "superInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "childInstances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subInstanceId": {
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "subInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "ID for an alternative title qualifier"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Resource identifier value"
          },
          "identifierTypeId": {
            "type": "string",
            "description": "Resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)"
          }
        },
        "additionalProperties": false,
        "required": [
          "value",
          "identifierTypeId"
        ]
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "ID for the contributor type term defined as a referencetable in settings"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "Contributor type terms defined by the MARC code list for relators"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "List of classification schemas (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "The value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "instanceTypeId": {
      "type": "string",
      "description": "The unique term for the resource type whether it's from the RDA content term list of locally defined"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "The unique term for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string"
      }
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes), and administrative notes",
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "RDA mode of issuance is a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc."
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      }
    },
    "sourceRecordFormat": {
      "description": "Format of the instance source record, if a source record exists",
      "type": "string",
      "enum": ["MARC-JSON"],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "links": {
        "type": "object",
        "properties": {
          "self": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "self"
        ]
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers

Location: required (string)
URI to the created instance item

Body

Media type: application/json

Type: any

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add instance -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create instances -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

DELETE /inventory/instances

DELETE /inventory/instances

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 204

All instances deleted

GET /inventory/instances/{instanceId}

Retrieve instance item with given {instanceId}

GET /inventory/instances/{instanceId}

URI Parameters

instanceId: required (string)

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "type": "object",
  "properties": {
    "@context": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory;  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)"
    },
    "parentInstances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "superInstanceId": {
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "superInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "childInstances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subInstanceId": {
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "subInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "ID for an alternative title qualifier"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Resource identifier value"
          },
          "identifierTypeId": {
            "type": "string",
            "description": "Resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)"
          }
        },
        "additionalProperties": false,
        "required": [
          "value",
          "identifierTypeId"
        ]
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "ID for the contributor type term defined as a referencetable in settings"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "Contributor type terms defined by the MARC code list for relators"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "List of classification schemas (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "The value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "instanceTypeId": {
      "type": "string",
      "description": "The unique term for the resource type whether it's from the RDA content term list of locally defined"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "The unique term for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string"
      }
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes), and administrative notes",
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "RDA mode of issuance is a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc."
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      }
    },
    "sourceRecordFormat": {
      "description": "Format of the instance source record, if a source record exists",
      "type": "string",
      "enum": ["MARC-JSON"],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "links": {
        "type": "object",
        "properties": {
          "self": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "self"
        ]
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /inventory/instances/{instanceId}

Delete instance item with given {instanceId}

DELETE /inventory/instances/{instanceId}

URI Parameters

instanceId: required (string)

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete instance -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /inventory/instances/{instanceId}

Update instance item with given {instanceId}

PUT /inventory/instances/{instanceId}

URI Parameters

instanceId: required (string)

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An instance record",
  "type": "object",
  "properties": {
    "@context": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "The system assigned unique ID of the instance record; UUID"
    },
    "hrid": {
      "type": "string",
      "description": "The human readable ID, also called eye readable ID. A system-assigned sequential ID which maps to the Instance ID"
    },
    "source": {
      "type": "string",
      "description": "The metadata source and its format of the underlying record to the instance record. (e.g. FOLIO if it's a record created in Inventory;  MARC if it's a MARC record created in MARCcat or EPKB if it's a record coming from eHoldings)"
    },
    "parentInstances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "superInstanceId": {
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "superInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "childInstances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subInstanceId": {
            "type": "string"
          },
          "instanceRelationshipTypeId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "subInstanceId",
          "instanceRelationshipTypeId"
        ]
      }
    },
    "title": {
      "type": "string",
      "description": "The primary title (or label) associated with the resource"
    },
    "indexTitle": {
      "type": "string",
      "description": "Title normalized for browsing and searching; based on the title with articles removed"
    },
    "alternativeTitles": {
      "type": "array",
      "description": "List of alternative titles for the resource (e.g. original language version title of a movie)",
      "items": {
        "type": "object",
        "properties": {
          "alternativeTitleTypeId": {
            "type": "string",
            "description": "ID for an alternative title qualifier"
          },
          "alternativeTitle": {
            "type": "string",
            "description": "An alternative title for the resource"
          }
        }
      },
      "uniqueItems": true
    },
    "editions": {
      "type": "array",
      "description": "The edition statement, imprint and other publication source information",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "series": {
      "type": "array",
      "description": "List of series titles associated with the resource (e.g. Harry Potter)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "identifiers": {
      "type": "array",
      "description": "An extensible set of name-value pairs of identifiers associated with the resource",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Resource identifier value"
          },
          "identifierTypeId": {
            "type": "string",
            "description": "Resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)"
          }
        },
        "additionalProperties": false,
        "required": [
          "value",
          "identifierTypeId"
        ]
      }
    },
    "contributors": {
      "type": "array",
      "description": "List of contributors",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Personal name, corporate name, meeting name"
          },
          "contributorTypeId": {
            "type": "string",
            "description": "ID for the contributor type term defined as a referencetable in settings"
          },
          "contributorTypeText": {
            "type": "string",
            "description": "Free text element for adding contributor type terms other that defined by the MARC code list for relators"
          },
          "contributorNameTypeId": {
            "type": "string",
            "description": "Contributor type terms defined by the MARC code list for relators"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary contributor"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "contributorNameTypeId"
        ]
      }
    },
    "subjects": {
      "type": "array",
      "description": "List of subject headings",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "classifications": {
      "type": "array",
      "description": "List of classifications",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "classificationNumber": {
            "type": "string",
            "description": "Classification (e.g. classification scheme, classification schedule)"
          },
          "classificationTypeId": {
            "type": "string",
            "description": "List of classification schemas (e.g. LC, Canadian Classification, NLM, National Agricultural Library, UDC, and Dewey)"
          }
        },
        "additionalProperties": false,
        "required": [
          "classificationNumber",
          "classificationTypeId"
        ]
      }
    },
    "publication": {
      "type": "array",
      "description": "List of publication items",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string",
            "description": "Name of publisher, distributor, etc."
          },
          "place": {
            "type": "string",
            "description": "Place of publication, distribution, etc."
          },
          "dateOfPublication": {
            "type": "string",
            "description": "Date (year YYYY) of publication, distribution, etc."
          },
          "role": {
            "type": "string",
            "description": "The role of the publisher, distributor, etc."
          }
        }
      }
    },
    "publicationFrequency": {
      "type": "array",
      "description": "List of intervals at which a serial appears (e.g. daily, weekly, monthly, quarterly, etc.)",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "publicationRange": {
      "type": "array",
      "description": "The range of sequential designation/chronology of publication, or date range",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    },
    "electronicAccess": {
      "type": "array",
      "description": "List of electronic access items",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string",
            "description": "Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources"
          },
          "linkText": {
            "type": "string",
            "description": "The value of the MARC tag field 856 2nd indicator, where the values are: no information provided, resource, version of resource, related resource, no display constant generated"
          },
          "materialsSpecification": {
            "type": "string",
            "description": "Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)"
          },
          "publicNote": {
            "type": "string",
            "description": "URL public note to be displayed in the discovery"
          },
          "relationshipId": {
            "type": "string",
            "description": "Relationship between the electronic resource at the location identified and the item described in the record as a whole"
          }
        },
        "additionalProperties": false,
        "required": [
          "uri"
        ]
      }
    },
    "instanceTypeId": {
      "type": "string",
      "description": "The unique term for the resource type whether it's from the RDA content term list of locally defined"
    },
    "instanceFormatIds": {
      "type": "array",
      "description": "The unique term for the format whether it's from the RDA carrier term list of locally defined",
      "items": {
        "type": "string"
      }
    },
    "physicalDescriptions": {
      "type": "array",
      "description": "Physical description of the described resource, including its extent, dimensions, and such other physical details as a description of any accompanying materials and unit type and size",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "description": "The set of languages used by the resource",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "notes": {
      "type": "array",
      "description": "Bibliographic notes (e.g. general notes, specialized notes), and administrative notes",
      "items": {
        "type": "string"
      }
    },
    "modeOfIssuanceId": {
      "type": "string",
      "description": "RDA mode of issuance is a categorization reflecting whether a resource is issued in one or more parts, the way it is updated, and whether its termination is predetermined or not (e.g. monograph,  sequential monograph, serial; integrating Resource, other)"
    },
    "catalogedDate": {
      "type": "string",
      "description": "Date or timestamp on an instance for when is was considered cataloged"
    },
    "previouslyHeld": {
      "type": "boolean",
      "description": "Records the fact that the resource was previously held by the library for things like Hathi access, etc."
    },
    "staffSuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed for others than catalogers"
    },
    "discoverySuppress": {
      "type": "boolean",
      "description": "Records the fact that the record should not be displayed in a discovery system"
    },
    "statisticalCodeIds": {
      "type": "array",
      "description": "List of statistical code IDs",
      "items": {
        "type": "string"
      }
    },
    "sourceRecordFormat": {
      "description": "Format of the instance source record, if a source record exists",
      "type": "string",
      "enum": ["MARC-JSON"],
      "readonly": true
    },
    "statusId": {
      "type": "string",
      "description": "Instance status term (e.g. cataloged, uncatalogued, batch loaded, temporary, other, not yet assigned)"
    },
    "statusUpdatedDate": {
      "type": "string",
      "description": "Date [or timestamp] for when the instance status was updated"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "links": {
        "type": "object",
        "properties": {
          "self": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "self"
        ]
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "title",
    "instanceTypeId"
  ]
}

Example:

{
  "@context": "http://localhost:9130/inventory/instance/context",
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "title": "ADVANCING LIBRARY EDUCATION: TECHNOLOGICAL INNOVATION AND INSTRUCTIONAL DESIGN",
  "links": {
    "self": "http://localhost:9130/inventory/instance/cd28da0f-a3e4-465c-82f1-acade4e8e170"
  },
  "source": "Local",
  "instanceTypeId": "abc5dd49-7ede-49cb-84db-6fac770279a8",
  "identifiers": [
    {
      "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422",
      "value": "9781466636897"
    }
  ],
  "contributors": [
    {
      "contributorNameTypeId": "2b94c631-fca9-a892-c730-03ee529ffe2a",
      "name": "Samuels, Simon"
    }
  ]
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update instance -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /inventory/instances/context

Provides Dublin Core context for instances

GET /inventory/instances/context

Response 200

Dublin Core context for instances

Body

Media type: application/json

Example:

{
  "@context": {
    "dcterms": "http://purl.org/dc/terms/",
    "title": "dcterms:title"
  }
}

POST /inventory/ingest/mods

POST /inventory/ingest/mods

Body

Media type: multipart/form-data

Properties:

file: required (file)
MODS file containing items to ingest

Response 202

Headers

location: required (string)
URI pointing to the location of ingest status

Response 400

Body

Media type: text/plain

Type: any

Example:

Cannot parse multiple files in a single request

Response 500

Body

Media type: text/plain

Type: any

GET /inventory/ingest/mods/status/{id}

Status of a MODS ingest

GET /inventory/ingest/mods/status/{id}

URI Parameters

id: required (string)

Response 200

Body

Media type: application/json

Example:

{
  "status": "Completed"
}

Response 500

Body

Media type: text/plain

Type: any

Inventory API (v8.3)

Table of contents

Inventory API

/inventory

GET /inventory/items

Query Parameters

Response 200

Response 400

Response 401

Response 500

POST /inventory/items

Query Parameters

Response 201

Headers

Response 400

Response 401

Response 500

DELETE /inventory/items

Query Parameters

Response 204

GET /inventory/items/{itemId}

URI Parameters

Query Parameters

Response 200

Response 404

Response 500

DELETE /inventory/items/{itemId}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

PUT /inventory/items/{itemId}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

GET /inventory/instances

Query Parameters

Response 200

Response 400

Response 401

Response 500

POST /inventory/instances

Query Parameters

Response 201

Headers

Response 400

Response 401

Response 500

DELETE /inventory/instances

Query Parameters

Response 204

GET /inventory/instances/{instanceId}

URI Parameters

Query Parameters

Response 200

Response 404

Response 500

DELETE /inventory/instances/{instanceId}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

PUT /inventory/instances/{instanceId}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

GET /inventory/instances/context

Response 200

POST /inventory/ingest/mods

Response 202