23.11 23.05 22.11 22.05 21.11 21.05 20.11 20.05 19.11 Development

Koha REST API (1)

Download OpenAPI specification:Download

Background

The API supports two sets of endpoints, one targetted at library staff and the other at at library users.

Those endpoints under the /public path are aimed at delivering functionality tailored to library users and offer a more restricted set of functions, overrides and data in thier responses for data privacy and library policy reasons. Many of these endpoints do not require authentication for fetching public data, though an authenticated session will expose additional options and allow users to see more data where it is part of their own record.

All other endpoints are targetted at the staff interface level and allow for additional functionality and a more unrestricted view of data. These endpoints, however, have a level of redaction built in for resources that the api consumer should not have access to. For example, user data for users who do not belong to the same library or library group of your api user will be reduced to just minimum neccesary for a valid response. Object keys will be consistent for all responses, but their values may be removed depending on access.

Authentication

The API supports the following authentication mechanisms

  • HTTP Basic authentication
  • OAuth2 (client credentials grant)
  • Cookie-based

Both Basic authentication and the OAuth2 flow, need to be enabled by system preferences.

Authorization

The API uses existing user profiles to restrict access to resources based on user permissions and the library the API user is assigned to. This may result, at times, in resources being returned in a redacted form with all keys present but sensative values nulled.

We do not yet support OAuth Scopes or the Authorization Code grant flow.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "error": "Current settings prevent the passed due date to be applied",
  "error_code": "invalid_due_date"
}

Note: Some routes might offer additional attributes in their error responses but that"s subject to change and thus not documented.

Filtering responses

The API allows for some advanced response filtering using a JSON based query syntax. The query can be added to the requests:

  • as a query parameter q=
  • in the request body

For simple field equality matches we can use { "fieldname": "value" } where the fieldname matches one of the fields as described in the particular endpoints response object.

We can refine that with more complex matching clauses by nesting a the clause into the object; { "fieldname": { "clause": "value" } }.

Available matching clauses include >, <, >=, <=, -like, and -not_like.

We can filter on multiple fields by adding them to the JSON respresentation. Adding at HASH level will result in an "AND" query, whilst combinding them in an ARRAY will result in an "OR" query: { "field1": "value2", "field2": "value2" } will filter the response to only those results with both field1 containing value2 AND field2 containing value2 for example.

Additionally, if you are requesting related data be embedded into the response one can query on the related data using dot notation in the field names.

Examples

The following request would return any patron with firstname "Henry" and lastname "Acevedo";

curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'

The following request would return any patron whose lastname begins with "Ace";

curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw '{ "surname": { "-like": "Ace%" }'

The following request would return any patron whose lastname is "Acevedo" OR "Bernardo"

curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'

The following request embeds the related patron extended attributes data and filters on it.

curl -u koha:koha =--request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header 'x-koha-embed: extended_attributes' --data-raw '{ "extended_attributes.code": "internet", "extended_attributes.attribute": "1" }'

Special headers

x-koha-embed

This optional header allows the api consumer to request additional related data to be returned in the api response. It also allows for cross referencing in the queries as described above. It accepts a comma delimited list of relation names.

Relations may on occasion also support dot delimited nesting to allow traversal.

x-koha-library

This optional header should be passed to give your api request a library context; If it is not included in the request, then the request context will default to using your api comsumer"s assigned home library.

Article requests

Manage article requests

Cancel article requests

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
article_request_id
required
integer

Article request identifier

query Parameters
cancellation_reason
string

Article request cancellation reason

notes
string

Article request custom cancellation reason

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Cancel patron's article requests

koha-authorization: {"allow-owner":true}
path Parameters
patron_id
required
integer

Internal patron identifier

article_request_id
required
integer

Article request identifier

query Parameters
cancellation_reason
string

Article request cancellation reason

notes
string

Article request custom cancellation reason

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Authorised value categories

Manage authorised value categories

List authorised value categories

koha-authorization: {"permissions":{"catalogue":1}}
query Parameters
_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-embed
Array of strings
Items Value: "authorised_values"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Authorised values

Manage authorised values

List authorised values for a given category

koha-authorization: {"permissions":{"catalogue":1}}
path Parameters
authorised_value_category_name
required
string

category name

query Parameters
authorised_value_id
integer

Case insensitive search on authorised value id

category_name
string

Case insensitive search on authorised value category name

value
string

Case insensitive search on value

description
string

Case insensitive search on description

opac_description
string

Case insensitive search on opac description

image_url
string

Case insensitive search on image url

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Batch import profiles

Manage batch import profiles

List batch import profiles

koha-authorization: {"permissions":{"tools":"stage_marc_import"}}
query Parameters
name
string

Search on profile's name

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-request-id
integer

Request id header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Add batch import profile

koha-authorization: {"permissions":{"tools":"stage_marc_import"}}
Request Body schema: application/json

A JSON object containing a import batch profile

name
string

name of this profile

matcher_id
integer or null

the id of the match rule used (matchpoints.matcher_id)

template_id
integer or null

the id of the marc modification template

overlay_action
string or null

how to handle duplicate records

nomatch_action
string or null

how to handle records where no match is found

item_action
string or null

what to do with item records

parse_items
boolean or null

should items be parsed

record_type
string or null

type of record in the batch

encoding
string or null

file encoding

format
string or null

marc format

comments
string or null

any comments added when the file was uploaded

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "matcher_id": 0,
  • "template_id": 0,
  • "overlay_action": "string",
  • "nomatch_action": "string",
  • "item_action": "string",
  • "parse_items": true,
  • "record_type": "string",
  • "encoding": "string",
  • "format": "string",
  • "comments": "string"
}

Response samples

Content type
application/json
{
  • "profile_id": 0,
  • "name": "string",
  • "matcher_id": 0,
  • "template_id": 0,
  • "overlay_action": "string",
  • "nomatch_action": "string",
  • "item_action": "string",
  • "parse_items": true,
  • "record_type": "string",
  • "encoding": "string",
  • "format": "string",
  • "comments": "string"
}

Update batch import profile

koha-authorization: {"permissions":{"tools":"stage_marc_import"}}
path Parameters
import_batch_profile_id
required
integer

Internal profile identifier

Request Body schema: application/json

A JSON object containing a import batch profile

name
string

name of this profile

matcher_id
integer or null

the id of the match rule used (matchpoints.matcher_id)

template_id
integer or null

the id of the marc modification template

overlay_action
string or null

how to handle duplicate records

nomatch_action
string or null

how to handle records where no match is found

item_action
string or null

what to do with item records

parse_items
boolean or null

should items be parsed

record_type
string or null

type of record in the batch

encoding
string or null

file encoding

format
string or null

marc format

comments
string or null

any comments added when the file was uploaded

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "matcher_id": 0,
  • "template_id": 0,
  • "overlay_action": "string",
  • "nomatch_action": "string",
  • "item_action": "string",
  • "parse_items": true,
  • "record_type": "string",
  • "encoding": "string",
  • "format": "string",
  • "comments": "string"
}

Response samples

Content type
application/json
{
  • "profile_id": 0,
  • "name": "string",
  • "matcher_id": 0,
  • "template_id": 0,
  • "overlay_action": "string",
  • "nomatch_action": "string",
  • "item_action": "string",
  • "parse_items": true,
  • "record_type": "string",
  • "encoding": "string",
  • "format": "string",
  • "comments": "string"
}

Delete batch import profile

koha-authorization: {"permissions":{"tools":"stage_marc_import"}}
path Parameters
import_batch_profile_id
required
integer

Internal profile identifier

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Baskets

Manage baskets for the acquisitions module

List possibe managers for baskets

This resource returns a list of patron allowed to be a manager for baskets

koha-authorization: {"permissions":{"acquisition":"order_manage"}}
query Parameters
_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-embed
Array of strings
Items Value: "extended_attributes"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Authorities

Manage Authority records

List authorities

koha-authorization: {"permissions":{"catalogue":"1"}}
query Parameters
_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-request-id
integer

Request id header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
{
  • "error": "string",
  • "error_code": "string"
}

Add authority

Add an authority record to Koha. An optional x-authority-type may be passed to specify the cataloguing framework to be used (instead of the default).

The request body is expected to contain a MARC record in the format specified in the Content-type header you pass. Possible values for this header and the corresponding record formats expected are listed below:

  • application/marcxml+xml: MARCXML
  • application/marc-in-json: MARC-in-JSON
  • application/marc: Raw USMARC binary data
koha-authorization: {"permissions":{"editauthorities":"1"}}
header Parameters
x-authority-type
string

Authority type code. Use when content type is not application/json

x-koha-override
Array of strings
Items Enum: "any" "duplicate"

Overrides list sent as a request header

Responses

Get authority

koha-authorization: {"permissions":{"catalogue":"1"}}
path Parameters
authority_id
required
integer

Authority identifier

Responses

Response samples

Content type
{
  • "error": "string",
  • "error_code": "string"
}

Delete authority

koha-authorization: {"permissions":{"editauthorities":"1"}}
path Parameters
authority_id
required
integer

Authority identifier

Responses

Response samples

Content type
application/json
"string"

Update authority

koha-authorization: {"permissions":{"editauthorities":"1"}}
path Parameters
authority_id
required
integer

Authority identifier

header Parameters
x-authority-type
string

Authority type code. Use when content type is not application/json

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Biblios

Manage bibliographic records

Add biblio

Add a bibliographic record to Koha. An optional x-framework-id may be passed to specify the cataloguing framework to be used (instead of the default).

The request body is expected to contain a MARC record in the format specified in the Content-type header you pass. Possible values for this header and the corresponding record formats expected are listed below:

  • application/marcxml+xml: MARCXML
  • application/marc-in-json: MARC-in-JSON
  • application/marc: Raw USMARC binary data
koha-authorization: {"permissions":{"editcatalogue":"edit_catalogue"}}
header Parameters
x-framework-id
string

Framework id. Use when content type is not application/json

x-record-schema
string
Enum: "MARC21" "UNIMARC"

March schema. One of MARC21 or UNIMARC

x-confirm-not-duplicate
integer

Confirm the posted element is not a duplicate

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

List biblios

koha-authorization: {"permissions":{"catalogue":"1"}}
query Parameters
_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-request-id
integer

Request id header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
{
  • "error": "string",
  • "error_code": "string"
}

Get biblio

koha-authorization: {"permissions":{"catalogue":"1"}}
path Parameters
biblio_id
required
integer

Record internal identifier

Responses

Response samples

Content type
{
  • "error": "string",
  • "error_code": "string"
}

Delete biblio

koha-authorization: {"permissions":{"editcatalogue":"edit_catalogue"}}
path Parameters
biblio_id
required
integer

Record internal identifier

Responses

Response samples

Content type
application/json
"string"

Update biblio

Updates a bibliographic record to Koha. An optional x-framework-id may be passed, to specify the cataloguing framework to be used (instead of the default).

The request body is expected to contain a MARC record in the format specified by the Content-type header passed. Possible values for this headers and the corresponding record formats expected are listed below:

  • application/marcxml+xml: MARCXML
  • application/marc-in-json: MARC-in-JSON
  • application/marc: Raw USMARC binary data
koha-authorization: {"permissions":{"editcatalogue":"edit_catalogue"}}
path Parameters
biblio_id
required
integer

Record internal identifier

header Parameters
x-framework-id
string

Framework id. Use when content type is not application/json

x-record-schema
string
Enum: "MARC21" "UNIMARC"

March schema. One of MARC21 or UNIMARC

x-confirm-not-duplicate
integer

Confirm the posted element is not a duplicate

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Get items for a biblio

koha-authorization: {"permissions":{"catalogue":"1"}}
path Parameters
biblio_id
required
integer

Record internal identifier

query Parameters
_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

bookable
boolean

Limit to items that are bookable

header Parameters
x-koha-embed
Array of strings
Items Value: "+strings"

Embed list sent as a request header

x-koha-request-id
integer

Request id header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Add an item for a biblio

koha-authorization: {"permissions":{"editcatalogue":"edit_catalogue"}}
path Parameters
biblio_id
required
integer

Record internal identifier

Request Body schema: application/json

A JSON object containing information about the new item

item_id
integer

Internal item identifier

biblio_id
integer

Internal identifier for the parent bibliographic record

biblio
any
external_id
string or null

The item's barcode

acquisition_date
string or null <date>

The date the item was acquired

acquisition_source
string or null

Information about the acquisition source (it is not really a vendor id)

bookable
boolean

Allow bookings on this item.

home_library_id
string or null

Internal library id for the library the item belongs to

purchase_price
number or null

Purchase price

replacement_price
number or null

Cost the library charges to replace the item (e.g. if lost)

replacement_price_date
string or null <date>

The date the replacement price is effective from

last_checkout_date
string or null <date>

The date the item was last checked out

last_seen_date
string or null <date-time>

The date the item barcode was last scanned

not_for_loan_status
integer

Authorized value defining why this item is not for loan

effective_not_for_loan_status
integer

Authorized value defining why this item is not for not_for_loan_status

damaged_status
integer

Authorized value defining this item as damaged

damaged_date
string or null

The date and time an item was last marked as damaged, NULL if not damaged

lost_status
integer

Authorized value defining this item as lost

lost_date
string or null <date-time>

The date and time an item was last marked as lost, NULL if not lost

withdrawn
integer

Authorized value defining this item as withdrawn

withdrawn_date
string or null <date-time>

The date and time an item was last marked as withdrawn, NULL if not withdrawn

callnumber
string or null

Call number for this item

coded_location_qualifier
string or null

Coded location qualifier

checkouts_count
integer or null

Number of times this item has been checked out/issued

renewals_count
integer or null

Number of times this item has been renewed

holds_count
integer or null

Number of times this item has been placed on hold/reserved

restricted_status
integer or null

Authorized value defining use restrictions for this item

public_notes
string or null

Public notes on this item

internal_notes
string or null

Non-public notes on this item

holding_library_id
string or null

Library that is currently in possession item

timestamp
string <date-time>

Date and time this item was last altered

location
string or null

Authorized value for the shelving location for this item

permanent_location
string or null

Linked to the CART and PROC temporary locations feature, stores the permanent shelving location

checked_out_date
string or null <date>

Defines if item is checked out (NULL for not checked out, and checkout date for checked out)

call_number_source
string or null

Classification source used on this item

call_number_sort
string or null

?

collection_code
string or null

Authorized value for the collection code associated with this item

materials_notes
string or null

Materials specified

uri
string or null

URL for the item

item_type_id
string or null

Itemtype defining the type for this item

effective_item_type_id
string or null

Effective itemtype defining the type for this item_id

extended_subfields
string or null

Additional 952 subfields in XML format

serial_issue_number
string or null

serial enumeration/chronology for the item

copy_number
string or null

Copy number

inventory_number
string or null

Inventory number

new_status
string or null

'new' value, whatever free-text information.

exclude_from_local_holds_priority
boolean

Exclude this item from local holds priority.

return_claims
Array of any

An array of all return claims associated with this item

return_claim
object or null
_strings
object or null

A return claims object if one exists that's unresolved

Responses

Request samples

Content type
application/json
{
  • "item_id": 0,
  • "biblio_id": 0,
  • "biblio": null,
  • "external_id": "string",
  • "acquisition_date": "2019-08-24",
  • "acquisition_source": "string",
  • "bookable": true,
  • "home_library_id": "string",
  • "purchase_price": 0,
  • "replacement_price": 0,
  • "replacement_price_date": "2019-08-24",
  • "last_checkout_date": "2019-08-24",
  • "last_seen_date": "2019-08-24T14:15:22Z",
  • "not_for_loan_status": 0,
  • "effective_not_for_loan_status": 0,
  • "damaged_status": 0,
  • "damaged_date": "string",
  • "lost_status": 0,
  • "lost_date": "2019-08-24T14:15:22Z",
  • "withdrawn": 0,
  • "withdrawn_date": "2019-08-24T14:15:22Z",
  • "callnumber": "string",
  • "coded_location_qualifier": "string",
  • "checkouts_count": 0,
  • "renewals_count": 0,
  • "holds_count": 0,
  • "restricted_status": 0,
  • "public_notes": "string",
  • "internal_notes": "string",
  • "holding_library_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "location": "string",
  • "permanent_location": "string",
  • "checked_out_date": "2019-08-24",
  • "call_number_source": "string",
  • "call_number_sort": "string",
  • "collection_code": "string",
  • "materials_notes": "string",
  • "uri": "string",
  • "item_type_id": "string",
  • "effective_item_type_id": "string",
  • "extended_subfields": "string",
  • "serial_issue_number": "string",
  • "copy_number": "string",
  • "inventory_number": "string",
  • "new_status": "string",
  • "exclude_from_local_holds_priority": true,
  • "return_claims": [
    ],
  • "return_claim": { },
  • "_strings": { }
}

Response samples

Content type
application/json
{
  • "item_id": 0,
  • "biblio_id": 0,
  • "biblio": null,
  • "external_id": "string",
  • "acquisition_date": "2019-08-24",
  • "acquisition_source": "string",
  • "bookable": true,
  • "home_library_id": "string",
  • "purchase_price": 0,
  • "replacement_price": 0,
  • "replacement_price_date": "2019-08-24",
  • "last_checkout_date": "2019-08-24",
  • "last_seen_date": "2019-08-24T14:15:22Z",
  • "not_for_loan_status": 0,
  • "effective_not_for_loan_status": 0,
  • "damaged_status": 0,
  • "damaged_date": "string",
  • "lost_status": 0,
  • "lost_date": "2019-08-24T14:15:22Z",
  • "withdrawn": 0,
  • "withdrawn_date": "2019-08-24T14:15:22Z",
  • "callnumber": "string",
  • "coded_location_qualifier": "string",
  • "checkouts_count": 0,
  • "renewals_count": 0,
  • "holds_count": 0,
  • "restricted_status": 0,
  • "public_notes": "string",
  • "internal_notes": "string",
  • "holding_library_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "location": "string",
  • "permanent_location": "string",
  • "checked_out_date": "2019-08-24",
  • "call_number_source": "string",
  • "call_number_sort": "string",
  • "collection_code": "string",
  • "materials_notes": "string",
  • "uri": "string",
  • "item_type_id": "string",
  • "effective_item_type_id": "string",
  • "extended_subfields": "string",
  • "serial_issue_number": "string",
  • "copy_number": "string",
  • "inventory_number": "string",
  • "new_status": "string",
  • "exclude_from_local_holds_priority": true,
  • "return_claims": [
    ],
  • "return_claim": { },
  • "_strings": { }
}

Update an item for a biblio

koha-authorization: {"permissions":{"editcatalogue":"edit_catalogue"}}
path Parameters
biblio_id
required
integer

Record internal identifier

item_id
required
integer

Internal item identifier

Request Body schema: application/json

A JSON object containing information about the item

item_id
integer

Internal item identifier

biblio_id
integer

Internal identifier for the parent bibliographic record

biblio
any
external_id
string or null

The item's barcode

acquisition_date
string or null <date>

The date the item was acquired

acquisition_source
string or null

Information about the acquisition source (it is not really a vendor id)

bookable
boolean

Allow bookings on this item.

home_library_id
string or null

Internal library id for the library the item belongs to

purchase_price
number or null

Purchase price

replacement_price
number or null

Cost the library charges to replace the item (e.g. if lost)

replacement_price_date
string or null <date>

The date the replacement price is effective from

last_checkout_date
string or null <date>

The date the item was last checked out

last_seen_date
string or null <date-time>

The date the item barcode was last scanned

not_for_loan_status
integer

Authorized value defining why this item is not for loan

effective_not_for_loan_status
integer

Authorized value defining why this item is not for not_for_loan_status

damaged_status
integer

Authorized value defining this item as damaged

damaged_date
string or null

The date and time an item was last marked as damaged, NULL if not damaged

lost_status
integer

Authorized value defining this item as lost

lost_date
string or null <date-time>

The date and time an item was last marked as lost, NULL if not lost

withdrawn
integer

Authorized value defining this item as withdrawn

withdrawn_date
string or null <date-time>

The date and time an item was last marked as withdrawn, NULL if not withdrawn

callnumber
string or null

Call number for this item

coded_location_qualifier
string or null

Coded location qualifier

checkouts_count
integer or null

Number of times this item has been checked out/issued

renewals_count
integer or null

Number of times this item has been renewed

holds_count
integer or null

Number of times this item has been placed on hold/reserved

restricted_status
integer or null

Authorized value defining use restrictions for this item

public_notes
string or null

Public notes on this item

internal_notes
string or null

Non-public notes on this item

holding_library_id
string or null

Library that is currently in possession item

timestamp
string <date-time>

Date and time this item was last altered

location
string or null

Authorized value for the shelving location for this item

permanent_location
string or null

Linked to the CART and PROC temporary locations feature, stores the permanent shelving location

checked_out_date
string or null <date>

Defines if item is checked out (NULL for not checked out, and checkout date for checked out)

call_number_source
string or null

Classification source used on this item

call_number_sort
string or null

?

collection_code
string or null

Authorized value for the collection code associated with this item

materials_notes
string or null

Materials specified

uri
string or null

URL for the item

item_type_id
string or null

Itemtype defining the type for this item

effective_item_type_id
string or null

Effective itemtype defining the type for this item_id

extended_subfields
string or null

Additional 952 subfields in XML format

serial_issue_number
string or null

serial enumeration/chronology for the item

copy_number
string or null

Copy number

inventory_number
string or null

Inventory number

new_status
string or null

'new' value, whatever free-text information.

exclude_from_local_holds_priority
boolean

Exclude this item from local holds priority.

return_claims
Array of any

An array of all return claims associated with this item

return_claim
object or null
_strings
object or null

A return claims object if one exists that's unresolved

Responses

Request samples

Content type
application/json
{
  • "item_id": 0,
  • "biblio_id": 0,
  • "biblio": null,
  • "external_id": "string",
  • "acquisition_date": "2019-08-24",
  • "acquisition_source": "string",
  • "bookable": true,
  • "home_library_id": "string",
  • "purchase_price": 0,
  • "replacement_price": 0,
  • "replacement_price_date": "2019-08-24",
  • "last_checkout_date": "2019-08-24",
  • "last_seen_date": "2019-08-24T14:15:22Z",
  • "not_for_loan_status": 0,
  • "effective_not_for_loan_status": 0,
  • "damaged_status": 0,
  • "damaged_date": "string",
  • "lost_status": 0,
  • "lost_date": "2019-08-24T14:15:22Z",
  • "withdrawn": 0,
  • "withdrawn_date": "2019-08-24T14:15:22Z",
  • "callnumber": "string",
  • "coded_location_qualifier": "string",
  • "checkouts_count": 0,
  • "renewals_count": 0,
  • "holds_count": 0,
  • "restricted_status": 0,
  • "public_notes": "string",
  • "internal_notes": "string",
  • "holding_library_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "location": "string",
  • "permanent_location": "string",
  • "checked_out_date": "2019-08-24",
  • "call_number_source": "string",
  • "call_number_sort": "string",
  • "collection_code": "string",
  • "materials_notes": "string",
  • "uri": "string",
  • "item_type_id": "string",
  • "effective_item_type_id": "string",
  • "extended_subfields": "string",
  • "serial_issue_number": "string",
  • "copy_number": "string",
  • "inventory_number": "string",
  • "new_status": "string",
  • "exclude_from_local_holds_priority": true,
  • "return_claims": [
    ],
  • "return_claim": { },
  • "_strings": { }
}

Response samples

Content type
application/json
{
  • "item_id": 0,
  • "biblio_id": 0,
  • "biblio": null,
  • "external_id": "string",
  • "acquisition_date": "2019-08-24",
  • "acquisition_source": "string",
  • "bookable": true,
  • "home_library_id": "string",
  • "purchase_price": 0,
  • "replacement_price": 0,
  • "replacement_price_date": "2019-08-24",
  • "last_checkout_date": "2019-08-24",
  • "last_seen_date": "2019-08-24T14:15:22Z",
  • "not_for_loan_status": 0,
  • "effective_not_for_loan_status": 0,
  • "damaged_status": 0,
  • "damaged_date": "string",
  • "lost_status": 0,
  • "lost_date": "2019-08-24T14:15:22Z",
  • "withdrawn": 0,
  • "withdrawn_date": "2019-08-24T14:15:22Z",
  • "callnumber": "string",
  • "coded_location_qualifier": "string",
  • "checkouts_count": 0,
  • "renewals_count": 0,
  • "holds_count": 0,
  • "restricted_status": 0,
  • "public_notes": "string",
  • "internal_notes": "string",
  • "holding_library_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "location": "string",
  • "permanent_location": "string",
  • "checked_out_date": "2019-08-24",
  • "call_number_source": "string",
  • "call_number_sort": "string",
  • "collection_code": "string",
  • "materials_notes": "string",
  • "uri": "string",
  • "item_type_id": "string",
  • "effective_item_type_id": "string",
  • "extended_subfields": "string",
  • "serial_issue_number": "string",
  • "copy_number": "string",
  • "inventory_number": "string",
  • "new_status": "string",
  • "exclude_from_local_holds_priority": true,
  • "return_claims": [
    ],
  • "return_claim": { },
  • "_strings": { }
}

Get valid pickup locations for a biblio

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}
path Parameters
biblio_id
required
integer

Record internal identifier

query Parameters
patron_id
required
integer

Internal patron identifier

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Get biblio (public)

path Parameters
biblio_id
required
integer

Record internal identifier

Responses

Response samples

Content type
No sample

getBiblioItemsPublic

path Parameters
biblio_id
required
integer

Record internal identifier

query Parameters
_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-embed
Array of strings
Items Value: "+strings"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

set biblio rating (public)

path Parameters
biblio_id
required
integer

Record internal identifier

Request Body schema: application/json

A JSON object containing rating information

rating
required
integer or null

the rating

Responses

Request samples

Content type
application/json
{
  • "rating": 0
}

Response samples

Content type
application/json
{
  • "rating": 0,
  • "average": 0,
  • "count": 0
}

Cashups

Manage cash register cashups

List cashups for the cash register

koha-authorization: {"permissions":{"cash_management":"cashup"}}
path Parameters
cash_register_id
required
integer

Cash register internal identifier

query Parameters
_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-request-id
integer

Request id header

x-koha-embed
Array of strings
Items Value: "manager"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Get cashup

koha-authorization: {"permissions":{"cash_management":"cashup"}}
path Parameters
cashup_id
required
integer

Cashup internal identifier

header Parameters
x-koha-embed
Array of strings
Items Value: "summary"

Embed list sent as a request header

Responses

Response samples

Content type
application/json
{
  • "cashup_id": 0,
  • "cash_register_id": 0,
  • "manager_id": 0,
  • "manager": { },
  • "amount": 0,
  • "timestamp": "2019-08-24T14:15:22Z",
  • "summary": { }
}

Checkouts

Manage checkouts

List checkouts for a biblio

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
biblio_id
required
integer

Record internal identifier

query Parameters
_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

q
Array of strings

Query filter sent as a request parameter

checked_in
boolean

By default, current checkouts are returned, when this is true then checked in checkouts are returned as result.

header Parameters
x-koha-request-id
integer

Request id header

x-koha-embed
Array of strings
Items Enum: "issuer" "item" "patron" "library"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

List checkouts

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
query Parameters
patron_id
integer

Internal patron identifier

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

q
Array of strings

Query filter sent as a request parameter

checked_in
boolean

By default, current checkouts are returned, when this is true then checked in checkouts are returned as result.

header Parameters
x-koha-request-id
integer

Request id header

x-koha-embed
Array of strings
Items Enum: "issuer" "renewals"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Add a new checkout

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
query Parameters
confirmation
string

A JWT confirmation token

Request Body schema: application/json

A JSON object containing information about the new checkout

checkout_id
integer

internally assigned checkout identifier

patron_id
integer

Internal patron identifier

item_id
integer or null

internal identifier of checked out item

due_date
string <date-time>

Due date

library_id
string or null

code of the library the item was checked out

issuer_id
integer or null

internally assigned for the user that processed the checkout

checkin_date
string or null <date-time>

Date the item was returned

last_renewed_date
string or null <date-time>

Date the item was last renewed

renewals_count
integer or null

Number of renewals

unseen_renewals
integer or null

Number of consecutive unseen renewals

auto_renew
boolean

Auto renewal

auto_renew_error
string or null

Auto renewal error

timestamp
string

Last update time

checkout_date
string <date-time>

Date the item was issued

onsite_checkout
boolean

On site checkout

note
string or null

Issue note text

note_date
string or null <date>

Datetime of the issue note

note_seen
boolean or null

has the note been seen already

issuer
object or null

The object representing the checkout issuer

item
object or null

The object representing the checked out item

library
object or null

The object representing the checkout library

patron
object or null

The object representing the checkout patron

Responses

Request samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

Response samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

Get checkout

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
checkout_id
required
integer

Internal checkout identifier

header Parameters
x-koha-embed
Array of strings
Items Enum: "issuer" "renewals"

Embed list sent as a request header

Responses

Response samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

Get renewability for a checkout

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
checkout_id
required
integer

Internal checkout identifier

Responses

Response samples

Content type
application/json
{
  • "allows_renewal": true,
  • "max_renewals": 0,
  • "current_renewals": 0,
  • "unseen_renewals": 0,
  • "error": "string"
}

Renew a checkout

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
checkout_id
required
integer

Internal checkout identifier

query Parameters
seen
integer

Item was seen flag

Responses

Response samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

List renewals for a checkout

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
checkout_id
required
integer

Internal checkout identifier

header Parameters
x-koha-embed
Array of strings
Items Value: "renewer"

Embed list sent as a request header

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Renew a checkout

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
path Parameters
checkout_id
required
integer

Internal checkout identifier

query Parameters
seen
integer

Item was seen flag

Responses

Response samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

Get checkout availability

koha-authorization: {"permissions":{"circulate":"circulate_remaining_permissions"}}
query Parameters
patron_id
integer

Internal patron identifier

item_id
integer

Internal item identifier

Responses

Response samples

Content type
application/json
{
  • "blockers": { },
  • "confirms": { },
  • "warnings": { },
  • "confirmation_token": "string"
}

Get checkout availability

koha-authorization: {"allow-owner":true}
query Parameters
patron_id
integer

Internal patron identifier

item_id
integer

Internal item identifier

Responses

Response samples

Content type
application/json
{
  • "blockers": { },
  • "confirms": { },
  • "warnings": { },
  • "confirmation_token": "string"
}

Add a new checkout (public)

koha-authorization: {"allow-owner":true}
path Parameters
patron_id
required
integer

Internal patron identifier

query Parameters
confirmation
string

A JWT confirmation token

Request Body schema: application/json

A JSON object containing information about the new checkout

checkout_id
integer

internally assigned checkout identifier

patron_id
integer

Internal patron identifier

item_id
integer or null

internal identifier of checked out item

due_date
string <date-time>

Due date

library_id
string or null

code of the library the item was checked out

issuer_id
integer or null

internally assigned for the user that processed the checkout

checkin_date
string or null <date-time>

Date the item was returned

last_renewed_date
string or null <date-time>

Date the item was last renewed

renewals_count
integer or null

Number of renewals

unseen_renewals
integer or null

Number of consecutive unseen renewals

auto_renew
boolean

Auto renewal

auto_renew_error
string or null

Auto renewal error

timestamp
string

Last update time

checkout_date
string <date-time>

Date the item was issued

onsite_checkout
boolean

On site checkout

note
string or null

Issue note text

note_date
string or null <date>

Datetime of the issue note

note_seen
boolean or null

has the note been seen already

issuer
object or null

The object representing the checkout issuer

item
object or null

The object representing the checked out item

library
object or null

The object representing the checkout library

patron
object or null

The object representing the checkout patron

Responses

Request samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

Response samples

Content type
application/json
{
  • "checkout_id": 0,
  • "patron_id": 0,
  • "item_id": 0,
  • "due_date": "2019-08-24T14:15:22Z",
  • "library_id": "string",
  • "issuer_id": 0,
  • "checkin_date": "2019-08-24T14:15:22Z",
  • "last_renewed_date": "2019-08-24T14:15:22Z",
  • "renewals_count": 0,
  • "unseen_renewals": 0,
  • "auto_renew": true,
  • "auto_renew_error": "string",
  • "timestamp": "string",
  • "checkout_date": "2019-08-24T14:15:22Z",
  • "onsite_checkout": true,
  • "note": "string",
  • "note_date": "2019-08-24",
  • "note_seen": true,
  • "issuer": { },
  • "item": { },
  • "library": { },
  • "patron": { }
}

Circulation rules

Manage circulation rules

Get circulation rules kinds

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Cities

Manage cities

List cities

koha-authorization: {"permissions":{"catalogue":"1"}}
query Parameters
name
string

Case insensative search on city name

state
string

Case insensative search on city state

country
string

Case insensative search on city country

postal_code
string

Case Insensative search on city postal code

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-request-id
integer

Request id header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Add city

koha-authorization: {"permissions":{"parameters":"manage_cities"}}
Request Body schema: application/json

A JSON object containing informations about the new hold

name
required
string

city name

state
required
string or null

city state

postal_code
required
string or null

city postal code

country
required
string or null

city country

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "city_id": 0,
  • "name": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string"
}

Get city

koha-authorization: {"permissions":{"catalogue":"1"}}
path Parameters
city_id
required
integer

City internal identifier

Responses

Response samples

Content type
application/json
{
  • "city_id": 0,
  • "name": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string"
}

Update city

koha-authorization: {"permissions":{"parameters":"manage_cities"}}
path Parameters
city_id
required
integer

City internal identifier

Request Body schema: application/json

A city object

name
required
string

city name

state
required
string or null

city state

postal_code
required
string or null

city postal code

country
required
string or null

city country

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "city_id": 0,
  • "name": "string",
  • "state": "string",
  • "postal_code": "string",
  • "country": "string"
}

Delete city

koha-authorization: {"permissions":{"parameters":"manage_cities"}}
path Parameters
city_id
required
integer

City internal identifier

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Clubs

Manage patron clubs

Add a club hold

koha-authorization: {"permissions":{"reserveforothers":"1"}}
path Parameters
club_id
required
integer

Internal club identifier

Request Body schema: application/json

A JSON object containing informations about the new hold

biblio_id
integer or null

Internal biblio identifier

item_id
integer or null

Internal item identifier

pickup_library_id
required
string

Internal library identifier for the pickup library

expiration_date
string or null <date>

Hold end date

notes
string or null

Notes related to this hold

item_type
string or null

Limit hold on one itemtype (ignored for item-level holds)

default_patron_home
integer

For each patron, set pickup location to patron's home library if possible

Responses

Request samples

Content type
application/json
{
  • "biblio_id": 0,
  • "item_id": 0,
  • "pickup_library_id": "string",
  • "expiration_date": "2019-08-24",
  • "notes": "string",
  • "item_type": "string",
  • "default_patron_home": 0
}

Response samples

Content type
application/json
{
  • "club_hold_id": 0,
  • "club_id": 0,
  • "biblio_id": 0,
  • "item_id": "string",
  • "date_created": "2019-08-24T14:15:22Z"
}

ERM agreements

Manage ERM agreements

List agreements

koha-authorization: {"permissions":{"erm":1}}
query Parameters
agreement_id
integer

Case insensitive search on agreement agreement_id

vendor_id
integer

Case insensitive search on agreement vendor_id

name
string

Case insensitive search on agreement name

description
string

Case insensitive search on agreement description

status
string

Case insensitive search on agreement status

closure_reason
string

Case insensitive search on agreement closure_reason

is_perpetual
boolean

Case insensitive search on agreement is_perpetual

renewal_priority
string

Case insensitive search on agreement renewal_priority

license_info
string

Case insensitive search on agreement license_info

max_expiration_date
string <date>

filter by expired agreements

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-embed
Array of strings
Items Enum: "user_roles" "vendor"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Add agreement

koha-authorization: {"permissions":{"erm":1}}
Request Body schema: application/json

A JSON object containing information about the new agreement

vendor_id
integer or null

foreign key to aqbooksellers

name
required
string

name of the agreement

description
string or null

description of the agreement

status
required
string

current status of the agreement

closure_reason
string or null

reason of the closure

is_perpetual
required
boolean

is the agreement perpetual

renewal_priority
string or null

priority of the renewal

license_info
string or null

info about the license

Array of objects (erm_agreement_period)

periods defined for this agreement

Array of objects (erm_user_role)

role for users

Array of objects (erm_agreement_relationship)

agreement relationships

Array of objects (erm_agreement_license)

agreement licenses

Array of objects (erm_document)

documents

vendor
object or null

Information about the vendor

Responses

Request samples

Content type
application/json
{
  • "vendor_id": 0,
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "closure_reason": "string",
  • "is_perpetual": true,
  • "renewal_priority": "string",
  • "license_info": "string",
  • "periods": [
    ],
  • "user_roles": [
    ],
  • "agreement_relationships": [
    ],
  • "agreement_licenses": [
    ],
  • "documents": [
    ],
  • "vendor": { }
}

Response samples

Content type
application/json
[
  • {
    }
]

Get agreement

koha-authorization: {"permissions":{"erm":1}}
path Parameters
agreement_id
required
integer

Agreement internal identifier

header Parameters
x-koha-embed
Array of strings
Items Enum: "periods" "user_roles" "user_roles.patron" "agreement_licenses" "agreement_licenses.license" "agreement_relationships" "agreement_relationships.agreement" "agreement_relationships.related_agreement" "agreement_packages" "agreement_packages.package" "documents" "vendor"

Embed list sent as a request header

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update agreement

koha-authorization: {"permissions":{"erm":1}}
path Parameters
agreement_id
required
integer

Agreement internal identifier

header Parameters
x-koha-embed
Array of strings
Items Enum: "periods" "user_roles" "agreement_licenses" "agreement_relationships" "documents"

Embed list sent as a request header

Request Body schema: application/json

A JSON object containing new information about existing agreement

vendor_id
integer or null

foreign key to aqbooksellers

name
required
string

name of the agreement

description
string or null

description of the agreement

status
required
string

current status of the agreement

closure_reason
string or null

reason of the closure

is_perpetual
required
boolean

is the agreement perpetual

renewal_priority
string or null

priority of the renewal

license_info
string or null

info about the license

Array of objects (erm_agreement_period)

periods defined for this agreement

Array of objects (erm_user_role)

role for users

Array of objects (erm_agreement_relationship)

agreement relationships

Array of objects (erm_agreement_license)

agreement licenses

Array of objects (erm_document)

documents

vendor
object or null

Information about the vendor

Responses

Request samples

Content type
application/json
{
  • "vendor_id": 0,
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "closure_reason": "string",
  • "is_perpetual": true,
  • "renewal_priority": "string",
  • "license_info": "string",
  • "periods": [
    ],
  • "user_roles": [
    ],
  • "agreement_relationships": [
    ],
  • "agreement_licenses": [
    ],
  • "documents": [
    ],
  • "vendor": { }
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete agreement

koha-authorization: {"permissions":{"erm":1}}
path Parameters
agreement_id
required
integer

Agreement internal identifier

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

ERM configuration

Manage ERM configuration

get the ERM config

This resource returns a list of options needed for the ERM Vue app. EXPERIMENTAL - DO NOT RELY on this, it is subject to change!

koha-authorization: {"permissions":{"erm":1}}

Responses

Response samples

Content type
application/json
{
  • "settings": { }
}

ERM counter files

Manage ERM counter files

List counter_files

koha-authorization: {"permissions":{"erm":1}}
query Parameters
erm_counter_files_id
integer

Case insensitive search on counter_file erm_counter_files_id

usage_data_provider_id
integer

Case insensitive search on counter_file usage_data_provider_id

filename
string

Case insensitive search on counter_file filename

type
string

Case insensitive search on counter_file type

file_content
string

Case insensitive search on counter_file file_content

date_uploaded
string

Case insensitive search on counter_file date_uploaded

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

header Parameters
x-koha-embed
Array of strings
Items Value: "counter_logs"

Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Delete counter_file

koha-authorization: {"permissions":{"erm":1}}
path Parameters
erm_counter_files_id
required
integer

ERM counter_files internal identifier

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Download Counter file

koha-authorization: {"permissions":{"erm":1}}
path Parameters
erm_counter_files_id
required
integer

Case insensitive search on erm_counter_files_id

Responses

ERM counter logs

Manage ERM counter logs

List counter_logs

koha-authorization: {"permissions":{"erm":1}}
query Parameters
usage_data_provider_id
integer

Case insensitive search on counter_log usage_data_provider_id

_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

ERM counter registry

Retrieve counter registry data

List platforms currently registered with the counter registry

koha-authorization: {"permissions":{"erm":1}}
query Parameters
_match
string
Enum: "contains" "exact" "starts_with" "ends_with"

Matching criteria

_order_by
Array of strings

Sorting criteria

_page
integer

Page number, for paginated object listing

_per_page
integer

Page size, for paginated object listing

q
Array of strings

Query filter sent as a request parameter

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

ERM saved reports

Manage ERM saved reports

List default_usage_reports

koha-authorization: {"permissions":{"erm":1}}
query Parameters
erm_default_usage_report_id
integer

Case insensitive search on erm_default_usage_report_id

report_name
integer

Case insensitive search on default_usage_report repor