Koha REST API (1)

Download OpenAPI specification:Download

URL: https://koha-community.org/ License: GPL v3,

Introduction

This API is documented in OpenAPI format.

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.

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
in a special header x-koha-query

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 wilth 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.

Two factor authentication

Handle two factor authentication flows

Send OTP token for second step authentication

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

Responses

Response samples

200
400
403
500

Content type

application/json

{"access_token": "string",
"token_type": "string",
"expires_in": 0
}

Generate a secret

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

Responses

Response samples

201
400
403
500

Content type

application/json

{"secret32": "string",
"qr_code": "string",
"issuer": "string",
"key_id": "string"
}

Verify two-factor registration

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

Request Body schema: application/x-www-form-urlencoded

secret32 required	string the secret
pin_code required	string the pin code

Responses

Response samples

400
401
403
500

Content type

application/json

{"error": "string",
"error_code": "string"
}

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"
}

Identity providers

Manage identity providers

List configured authentication providers

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

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-query	string Query filter sent as a request header
x-koha-request-id	integer Request id header
x-koha-embed	Array of strings Items Value: "domains" Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
403
500
503

Content type

application/json

[{"identity_provider_id": 0,
"code": "string",
"description": "string",
"protocol": "OAuth",
"mapping": { },
"matchpoint": "email",
"config": { },
"icon_url": "string",
"domains": [null
]
}
]

Add a new authentication provider

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

Request Body schema: application/json

A JSON object containing OAuth provider parameters.

The config object required attributes depends on the chosen protocol

OAuth

Requires:

key
secret
authorize_url
token_url

OIDC

Requires:

key
secret
well_known_url

code required	string Authentication provider code
description	string User-oriented description for the provider
protocol required	string Enum: "OAuth" "OIDC" "CAS (not implemented)" "LDAP (not implemented)" Authentication protocol
mapping	object or null Attribute mapping
matchpoint	string Enum: "email" "userid" "cardnumber" Patron attribute that will be used to match
config required	object Configuration
icon_url	string or null Icon url
domains	Array of any or null Configured domains for the authentication provider

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"description": "string",
"protocol": "OAuth",
"mapping": { },
"matchpoint": "email",
"config": { },
"icon_url": "string",
"domains": [null
]
}

Response samples

201
400
403
500
503

Content type

application/json

{"identity_provider_id": 0,
"code": "string",
"description": "string",
"protocol": "OAuth",
"mapping": { },
"matchpoint": "email",
"config": { },
"icon_url": "string",
"domains": [null
]
}

Get authentication provider

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id

required

integer

Authentication provider internal identifier

header Parameters

x-koha-embed

Array of strings

Items Value: "domains"

Embed list sent as a request header

Responses

Response samples

200
404
500
503

Content type

application/json

{"identity_provider_id": 0,
"code": "string",
"description": "string",
"protocol": "OAuth",
"mapping": { },
"matchpoint": "email",
"config": { },
"icon_url": "string",
"domains": [null
]
}

Update an authentication provider

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id

required

integer

Authentication provider internal identifier

Request Body schema: application/json

A JSON object containing OAuth provider parameters.

The config object required attributes depends on the chosen protocol

OAuth

Requires:

key
secret
authorize_url
token_url

OIDC

Requires:

key
secret
well_known_url

code required	string Authentication provider code
description	string User-oriented description for the provider
protocol required	string Enum: "OAuth" "OIDC" "CAS (not implemented)" "LDAP (not implemented)" Authentication protocol
mapping	object or null Attribute mapping
matchpoint	string Enum: "email" "userid" "cardnumber" Patron attribute that will be used to match
config required	object Configuration
icon_url	string or null Icon url
domains	Array of any or null Configured domains for the authentication provider

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"description": "string",
"protocol": "OAuth",
"mapping": { },
"matchpoint": "email",
"config": { },
"icon_url": "string",
"domains": [null
]
}

Response samples

Content type

application/json

{"identity_provider_id": 0,
"code": "string",
"description": "string",
"protocol": "OAuth",
"mapping": { },
"matchpoint": "email",
"config": { },
"icon_url": "string",
"domains": [null
]
}

Delete authentication provider

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id

required

integer

Authentication provider internal identifier

Responses

Response samples

401
403
404
503

Content type

application/json

{"error": "string",
"error_code": "string"
}

Get authentication provider configured domains

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id

required

integer

Authentication provider 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-query	string Query filter sent as a request header
x-koha-request-id	integer Request id header
x-koha-embed	Array of strings Items Value: "domains" Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
404
500
503

Content type

application/json

[{"identity_provider_domain_id": 0,
"identity_provider_id": 0,
"domain": "string",
"auto_register": true,
"update_on_auth": true,
"default_library_id": "string",
"default_category_id": "string",
"allow_opac": true,
"allow_staff": true
}
]

Add an authentication provider domain

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id

required

integer

Authentication provider internal identifier

Request Body schema: application/json

An authentication provider domain object

identity_provider_id	integer Internally assigned authentication provider identifier
domain required	string or null Matching domain ('*' used as wildcard)
auto_register required	boolean If patrons will be generated on login if required
update_on_auth required	boolean If patron data is updated on login
default_library_id required	string or null Internal identifier for the default library to be assigned to the new patrons
default_category_id required	string or null Internal identifier for the default patron's category
allow_opac required	boolean If this domain can be used for OPAC login
allow_staff required	boolean If this domain can be used for staff login

Responses

Request samples

Payload

Content type

application/json

{"identity_provider_id": 0,
"domain": "string",
"auto_register": true,
"update_on_auth": true,
"default_library_id": "string",
"default_category_id": "string",
"allow_opac": true,
"allow_staff": true
}

Response samples

Content type

application/json

{"identity_provider_domain_id": 0,
"identity_provider_id": 0,
"domain": "string",
"auto_register": true,
"update_on_auth": true,
"default_library_id": "string",
"default_category_id": "string",
"allow_opac": true,
"allow_staff": true
}

Get authentication provider domain

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id required	integer Authentication provider internal identifier
identity_provider_domain_id required	integer Authentication provider domain internal identifier

Responses

Response samples

200
404
500
503

Content type

application/json

{"identity_provider_domain_id": 0,
"identity_provider_id": 0,
"domain": "string",
"auto_register": true,
"update_on_auth": true,
"default_library_id": "string",
"default_category_id": "string",
"allow_opac": true,
"allow_staff": true
}

Update an authentication provider domain

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id required	integer Authentication provider internal identifier
identity_provider_domain_id required	integer Authentication provider domain internal identifier

Request Body schema: application/json

An authentication provider domain object

identity_provider_id	integer Internally assigned authentication provider identifier
domain required	string or null Matching domain ('*' used as wildcard)
auto_register required	boolean If patrons will be generated on login if required
update_on_auth required	boolean If patron data is updated on login
default_library_id required	string or null Internal identifier for the default library to be assigned to the new patrons
default_category_id required	string or null Internal identifier for the default patron's category
allow_opac required	boolean If this domain can be used for OPAC login
allow_staff required	boolean If this domain can be used for staff login

Responses

Request samples

Payload

Content type

application/json

{"identity_provider_id": 0,
"domain": "string",
"auto_register": true,
"update_on_auth": true,
"default_library_id": "string",
"default_category_id": "string",
"allow_opac": true,
"allow_staff": true
}

Response samples

Content type

application/json

{"identity_provider_domain_id": 0,
"identity_provider_id": 0,
"domain": "string",
"auto_register": true,
"update_on_auth": true,
"default_library_id": "string",
"default_category_id": "string",
"allow_opac": true,
"allow_staff": true
}

Delete authentication provider

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}

path Parameters

identity_provider_id required	integer Authentication provider internal identifier
identity_provider_domain_id required	integer Authentication provider domain internal identifier

Responses

Response samples

401
403
404
503

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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

Response samples

200
403
500
503

Content type

application/json

[{"patron_id": 0,
"cardnumber": "string",
"surname": "string",
"firstname": "string",
"middle_name": "string",
"title": "string",
"other_name": "string",
"initials": "string",
"pronouns": "string",
"street_number": "string",
"street_type": "string",
"address": "string",
"address2": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"country": "string",
"email": "string",
"phone": "string",
"mobile": "string",
"fax": "string",
"secondary_email": "string",
"secondary_phone": "string",
"altaddress_street_number": "string",
"altaddress_street_type": "string",
"altaddress_address": "string",
"altaddress_address2": "string",
"altaddress_city": "string",
"altaddress_state": "string",
"altaddress_postal_code": "string",
"altaddress_country": "string",
"altaddress_email": "string",
"altaddress_phone": "string",
"date_of_birth": "2019-08-24",
"library_id": "string",
"category_id": "string",
"date_enrolled": "2019-08-24",
"expiry_date": "2019-08-24",
"date_renewed": "2019-08-24",
"incorrect_address": true,
"patron_card_lost": true,
"restricted": true,
"staff_notes": "string",
"relationship_type": "string",
"gender": "string",
"userid": "string",
"opac_notes": "string",
"altaddress_notes": "string",
"statistics_1": "string",
"statistics_2": "string",
"autorenew_checkouts": true,
"altcontact_firstname": "string",
"altcontact_surname": "string",
"altcontact_address": "string",
"altcontact_address2": "string",
"altcontact_city": "string",
"altcontact_state": "string",
"altcontact_postal_code": "string",
"altcontact_country": "string",
"altcontact_phone": "string",
"sms_number": "string",
"sms_provider_id": 0,
"privacy": 0,
"privacy_guarantor_checkouts": 0,
"privacy_guarantor_fines": true,
"check_previous_checkout": "string",
"updated_on": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"lang": "string",
"login_attempts": 0,
"overdrive_auth_token": "string",
"anonymized": true,
"extended_attributes": [{"extended_attribute_id": 0,
"type": "string",
"value": "string"
}
],
"checkouts_count": 0,
"overdues_count": 0,
"account_balance": 0,
"library": { }
}
]

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-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"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

application/json

{"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-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"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

application/json

{"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

header Parameters

x-koha-query	string Query filter 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

Payload

Content type

application/json

{ }

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",
"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": [null
],
"return_claim": { },
"_strings": { }
}
]

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)
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

Payload

Content type

application/json

{"item_id": 0,
"biblio_id": 0,
"biblio": null,
"external_id": "string",
"acquisition_date": "2019-08-24",
"acquisition_source": "string",
"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": [null
],
"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",
"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": [null
],
"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)
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

Payload

Content type

application/json

{"item_id": 0,
"biblio_id": 0,
"biblio": null,
"external_id": "string",
"acquisition_date": "2019-08-24",
"acquisition_source": "string",
"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": [null
],
"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",
"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": [null
],
"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

header Parameters

x-koha-query

string

Query filter sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

[{"library_id": "string",
"name": "string",
"address1": "string",
"address2": "string",
"address3": "string",
"postal_code": "string",
"city": "string",
"state": "string",
"country": "string",
"phone": "string",
"fax": "string",
"email": "string",
"illemail": "string",
"reply_to_email": "string",
"return_path_email": "string",
"url": "string",
"ip": "string",
"notes": "string",
"geolocation": "string",
"marc_org_code": "string",
"pickup_location": true,
"public": true,
"smtp_server": { },
"needs_override": true
}
]

Get biblio (public)

path Parameters

biblio_id

required

integer

Record internal identifier

Responses

Response samples

Content type

application/marcxml+xml

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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

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",
"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": [null
],
"return_claim": { },
"_strings": { }
}
]

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

Payload

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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

Response samples

200
403
404
500
503

Content type

application/json

[{"cashup_id": 0,
"cash_register_id": 0,
"manager_id": 0,
"manager": { },
"amount": 0,
"timestamp": "2019-08-24T14:15:22Z",
"summary": { }
}
]

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

200
403
404
500
503

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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

Response samples

200
403
404
500
503

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 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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

Response samples

200
403
404
500
503

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

200
403
404
500
503

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

200
403
404
500
503

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

201
403
404
500
503

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

200
403
404
500
503

Content type

application/json

[{"renewal_id": 0,
"checkout_id": 0,
"interface": "string",
"renewer_id": 0,
"renewal_date": "2019-08-24T14:15:22Z",
"seen": true,
"timestamp": "string",
"renewal_type": "Automatic",
"renewer": { }
}
]

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

201
403
404
500
503

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

200
403
500
503

Content type

application/json

{"property1": {"scope": ["branchcode"
]
},
"property2": {"scope": ["branchcode"
]
}
}

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-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

200
403
500
503

Content type

application/json

[{"city_id": 0,
"name": "string",
"state": "string",
"postal_code": "string",
"country": "string"
}
]

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

Payload

Content type

application/json

{"name": "string",
"state": "string",
"postal_code": "string",
"country": "string"
}

Response samples

201
401
403
500
503

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

200
404
500
503

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

Payload

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

401
403
404
500
503

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

Payload

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"
}

Funds

Manage funds for the acquisitions module

List funds

koha-authorization: {"permissions":{"acquisition":"budget_manage_all"}}

query Parameters

name	string Case insensitive search on fund name
fund_owner_id	integer Display only the funds that belongs to the given patron 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

header Parameters

x-koha-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

[{"fund_id": 0,
"code": "string",
"name": "string",
"library_id": "string",
"total_amount": 0,
"warn_at_percentage": 0,
"warn_at_amount": 0,
"notes": "string",
"budget_id": 0,
"timestamp": "2019-08-24T14:15:22Z",
"fund_owner_id": 0,
"fund_access": 0,
"parent_fund_id": 0,
"statistic1_auth_value_category": "string",
"statistic2_auth_value_category": "string"
}
]

List possibe owners for funds

This resource returns a list of patron allowed to be owner of funds

koha-authorization: {"permissions":{"acquisition":"budget_modify"}}

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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

Response samples

200
403
500
503

Content type

application/json

[{"patron_id": 0,
"cardnumber": "string",
"surname": "string",
"firstname": "string",
"middle_name": "string",
"title": "string",
"other_name": "string",
"initials": "string",
"pronouns": "string",
"street_number": "string",
"street_type": "string",
"address": "string",
"address2": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"country": "string",
"email": "string",
"phone": "string",
"mobile": "string",
"fax": "string",
"secondary_email": "string",
"secondary_phone": "string",
"altaddress_street_number": "string",
"altaddress_street_type": "string",
"altaddress_address": "string",
"altaddress_address2": "string",
"altaddress_city": "string",
"altaddress_state": "string",
"altaddress_postal_code": "string",
"altaddress_country": "string",
"altaddress_email": "string",
"altaddress_phone": "string",
"date_of_birth": "2019-08-24",
"library_id": "string",
"category_id": "string",
"date_enrolled": "2019-08-24",
"expiry_date": "2019-08-24",
"date_renewed": "2019-08-24",
"incorrect_address": true,
"patron_card_lost": true,
"restricted": true,
"staff_notes": "string",
"relationship_type": "string",
"gender": "string",
"userid": "string",
"opac_notes": "string",
"altaddress_notes": "string",
"statistics_1": "string",
"statistics_2": "string",
"autorenew_checkouts": true,
"altcontact_firstname": "string",
"altcontact_surname": "string",
"altcontact_address": "string",
"altcontact_address2": "string",
"altcontact_city": "string",
"altcontact_state": "string",
"altcontact_postal_code": "string",
"altcontact_country": "string",
"altcontact_phone": "string",
"sms_number": "string",
"sms_provider_id": 0,
"privacy": 0,
"privacy_guarantor_checkouts": 0,
"privacy_guarantor_fines": true,
"check_previous_checkout": "string",
"updated_on": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"lang": "string",
"login_attempts": 0,
"overdrive_auth_token": "string",
"anonymized": true,
"extended_attributes": [{"extended_attribute_id": 0,
"type": "string",
"value": "string"
}
],
"checkouts_count": 0,
"overdues_count": 0,
"account_balance": 0,
"library": { }
}
]

List possibe users for funds

This resource returns a list of patron allowed to be owner of funds

koha-authorization: {"permissions":{"acquisition":"budget_modify"}}

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-query	string Query filter sent as a request header
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

Payload

Content type

application/json

{ }

Response samples

200
403
500
503

Content type

application/json

[{"patron_id": 0,
"cardnumber": "string",
"surname": "string",
"firstname": "string",
"middle_name": "string",
"title": "string",
"other_name": "string",
"initials": "string",
"pronouns": "string",
"street_number": "string",
"street_type": "string",
"address": "string",
"address2": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"country": "string",
"email": "string",
"phone": "string",
"mobile": "string",
"fax": "string",
"secondary_email": "string",
"secondary_phone": "string",
"altaddress_street_number": "string",
"altaddress_street_type": "string",
"altaddress_address": "string",
"altaddress_address2": "string",
"altaddress_city": "string",
"altaddress_state": "string",
"altaddress_postal_code": "string",
"altaddress_country": "string",
"altaddress_email": "string",
"altaddress_phone": "string",
"date_of_birth": "2019-08-24",
"library_id": "string",
"category_id": "string",
"date_enrolled": "2019-08-24",
"expiry_date": "2019-08-24",
"date_renewed": "2019-08-24",
"incorrect_address": true,
"patron_card_lost": true,
"restricted": true,
"staff_notes": "string",
"relationship_type": "string",
"gender": "string",
"userid": "string",
"opac_notes": "string",
"altaddress_notes": "string",
"statistics_1": "string",
"statistics_2": "string",
"autorenew_checkouts": true,
"altcontact_firstname": "string",
"altcontact_surname": "string",
"altcontact_address": "string",
"altcontact_address2": "string",
"altcontact_city": "string",
"altcontact_state": "string",
"altcontact_postal_code": "string",
"altcontact_country": "string",
"altcontact_phone": "string",
"sms_number": "string",
"sms_provider_id": 0,
"privacy": 0,
"privacy_guarantor_checkouts": 0,
"privacy_guarantor_fines": true,
"check_previous_checkout": "string",
"updated_on": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"lang": "string",
"login_attempts": 0,
"overdrive_auth_token": "string",
"anonymized": true,
"extended_attributes": [{"extended_attribute_id": 0,
"type": "string",
"value": "string"
}
],
"checkouts_count": 0,
"overdues_count": 0,
"account_balance": 0,
"library": { }
}
]

Holds

Manage holds

List holds

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}

query Parameters

hold_id	integer Internal hold identifier
patron_id	integer Internal patron identifier
hold_date	string <date> Hold
biblio_id	integer Internal biblio identifier
item_group_id	integer Internal item group identifier
pickup_library_id	string Internal library identifier for the pickup library
cancellation_date	string <date> The date the hold was cancelled
notes	string Notes related to this hold
priority	integer Where in the queue the patron sits
status	string Found status
timestamp	string Time of latest update
item_id	integer Internal item identifier
waiting_date	string Date the item was marked as waiting for the patron
expiration_date	string Date the hold expires
lowest_priority	boolean Lowest priority
suspended	boolean Suspended
suspended_until	string Suspended until
non_priority	boolean Non priority hold
_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-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

[{"hold_id": 0,
"patron_id": 0,
"hold_date": "2019-08-24",
"biblio_id": 0,
"item_group_id": "string",
"pickup_library_id": "string",
"desk_id": 0,
"cancellation_date": "2019-08-24",
"cancellation_reason": "string",
"notes": "string",
"priority": 0,
"status": "string",
"timestamp": "2019-08-24T14:15:22Z",
"item_id": "string",
"waiting_date": "2019-08-24",
"expiration_date": "2019-08-24",
"lowest_priority": true,
"suspended": true,
"suspended_until": "2019-08-24T14:15:22Z",
"non_priority": true,
"item_type": "string",
"item_level": true
}
]

Place hold

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

header Parameters

x-koha-override

Array of strings

Items Value: "any"

Overrides list sent as a request header

Request Body schema: application/json

A JSON object containing informations about the new hold

patron_id required	integer Internal patron identifier
biblio_id	integer or null Internal biblio identifier
item_group_id	integer or null Internal item group identifier
hold_date	string or null <date> The date the hold was placed
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)
non_priority	boolean or null Set this hold as non priority

Responses

Request samples

Payload

Content type

application/json

{"patron_id": 0,
"biblio_id": 0,
"item_group_id": 0,
"hold_date": "2019-08-24",
"item_id": 0,
"pickup_library_id": "string",
"expiration_date": "2019-08-24",
"notes": "string",
"item_type": "string",
"non_priority": true
}

Response samples

Content type

application/json

{"hold_id": 0,
"patron_id": 0,
"hold_date": "2019-08-24",
"biblio_id": 0,
"item_group_id": "string",
"pickup_library_id": "string",
"desk_id": 0,
"cancellation_date": "2019-08-24",
"cancellation_reason": "string",
"notes": "string",
"priority": 0,
"status": "string",
"timestamp": "2019-08-24T14:15:22Z",
"item_id": "string",
"waiting_date": "2019-08-24",
"expiration_date": "2019-08-24",
"lowest_priority": true,
"suspended": true,
"suspended_until": "2019-08-24T14:15:22Z",
"non_priority": true,
"item_type": "string",
"item_level": true
}

Update hold

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

path Parameters

hold_id

required

integer

Internal hold identifier

Request Body schema: application/json

A JSON object containing fields to modify

priority	integer >= 1 Position in waiting queue
pickup_library_id	string Internal library identifier for the pickup library
suspended_until	string <date-time> Date until which the hold has been suspended

Responses

Request samples

Payload

Content type

application/json

{"priority": 1,
"pickup_library_id": "string",
"suspended_until": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"hold_id": 0,
"patron_id": 0,
"hold_date": "2019-08-24",
"biblio_id": 0,
"item_group_id": "string",
"pickup_library_id": "string",
"desk_id": 0,
"cancellation_date": "2019-08-24",
"cancellation_reason": "string",
"notes": "string",
"priority": 0,
"status": "string",
"timestamp": "2019-08-24T14:15:22Z",
"item_id": "string",
"waiting_date": "2019-08-24",
"expiration_date": "2019-08-24",
"lowest_priority": true,
"suspended": true,
"suspended_until": "2019-08-24T14:15:22Z",
"non_priority": true,
"item_type": "string",
"item_level": true
}

Update hold

This route is being deprecated and will be removed in future releases. Please migrate your project to use PATCH /holds/{hold_id} instead.

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

path Parameters

hold_id

required

integer

Internal hold identifier

Request Body schema: application/json

A JSON object containing fields to modify

priority	integer >= 1 Position in waiting queue
pickup_library_id	string Internal library identifier for the pickup library
suspended_until	string <date-time> Date until which the hold has been suspended

Responses

Request samples

Payload

Content type

application/json

{"priority": 1,
"pickup_library_id": "string",
"suspended_until": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"hold_id": 0,
"patron_id": 0,
"hold_date": "2019-08-24",
"biblio_id": 0,
"item_group_id": "string",
"pickup_library_id": "string",
"desk_id": 0,
"cancellation_date": "2019-08-24",
"cancellation_reason": "string",
"notes": "string",
"priority": 0,
"status": "string",
"timestamp": "2019-08-24T14:15:22Z",
"item_id": "string",
"waiting_date": "2019-08-24",
"expiration_date": "2019-08-24",
"lowest_priority": true,
"suspended": true,
"suspended_until": "2019-08-24T14:15:22Z",
"non_priority": true,
"item_type": "string",
"item_level": true
}

Cancel hold

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}

path Parameters

hold_id

required

integer

Internal hold identifier

Responses

Response samples

401
403
404
500
503

Content type

application/json

{"error": "string",
"error_code": "string"
}

Update pickup location for the hold

Set a new pickup location for the hold

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}

path Parameters

hold_id

required

integer

Internal hold identifier

Request Body schema: application/json

Pickup location

pickup_library_id

string

Internal identifier for the pickup library

Responses

Request samples

Payload

Content type

application/json

{"pickup_library_id": "string"
}

Response samples

Content type

application/json

{"pickup_library_id": "string"
}

Get valid pickup locations for hold

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}

path Parameters

hold_id

required

integer

Internal hold 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-override	Array of strings Items Value: "any" Overrides list sent as a request header
x-koha-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

[{"library_id": "string",
"name": "string",
"address1": "string",
"address2": "string",
"address3": "string",
"postal_code": "string",
"city": "string",
"state": "string",
"country": "string",
"phone": "string",
"fax": "string",
"email": "string",
"illemail": "string",
"reply_to_email": "string",
"return_path_email": "string",
"url": "string",
"ip": "string",
"notes": "string",
"geolocation": "string",
"marc_org_code": "string",
"pickup_location": true,
"public": true,
"smtp_server": { },
"needs_override": true
}
]

Update priority for the hold

koha-authorization: {"permissions":{"reserveforothers":"modify_holds_priority"}}

path Parameters

hold_id

required

integer

Internal hold identifier

Request Body schema: application/json

An integer representing the new priority to be set for the hold

integer

Responses

Request samples

Payload

Content type

application/json

0

0

Response samples

Content type

application/json

0

0

Suspend the hold

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}

path Parameters

hold_id

required

integer

Internal hold identifier

Request Body schema: application/json

A JSON object containing fields to modify

end_date

string <date>

Date the hold suspension expires

Responses

Request samples

Payload

Content type

application/json

{"end_date": "2019-08-24"
}

Response samples

Content type

application/json

{"error": "string",
"error_code": "string"
}

Resume hold

koha-authorization: {"permissions":{"reserveforothers":"place_holds"}}

path Parameters

hold_id

required

integer

Internal hold identifier

Responses

Response samples

Content type

application/json

{"error": "string",
"error_code": "string"
}

List holds for a patron

koha-authorization: {"permissions":{"borrowers":"edit_borrowers"}}

path Parameters

patron_id

required

integer

Internal patron 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-query	string Query filter 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

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

[{"hold_id": 0,
"patron_id": 0,
"hold_date": "2019-08-24",
"biblio_id": 0,
"item_group_id": "string",
"pickup_library_id": "string",
"desk_id": 0,
"cancellation_date": "2019-08-24",
"cancellation_reason": "string",
"notes": "string",
"priority": 0,
"status": "string",
"timestamp": "2019-08-24T14:15:22Z",
"item_id": "string",
"waiting_date": "2019-08-24",
"expiration_date": "2019-08-24",
"lowest_priority": true,
"suspended": true,
"suspended_until": "2019-08-24T14:15:22Z",
"non_priority": true,
"item_type": "string",
"item_level": true
}
]

ILL backends

Manage ILL module backends

List ILL backends

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

Responses

Response samples

Content type

application/json

[{"ill_backend_id": "string",
"capabilities": { },
"statuses": [{"str": "string",
"code": "string",
"type": "string",
"backend": "string",
"category": "string"
}
]
}
]

Get ILL backend

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

path Parameters

ill_backend_id

required

string

ILL backend id/name

header Parameters

x-koha-embed

Array of strings

Items Value: "statuses+strings"

Embed list sent as a request header

Responses

Response samples

Content type

application/json

{"ill_backend_id": "string",
"capabilities": { },
"statuses": [{"str": "string",
"code": "string",
"type": "string",
"backend": "string",
"category": "string"
}
]
}

ILL requests

Manage ILL requests

List ILL requests

koha-authorization: {"permissions":{"ill":"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-query	string Query filter sent as a request header
x-koha-request-id	integer Request id header
x-koha-embed	Array of strings Items Enum: "+strings" "biblio" "comments" "comments+count" "extended_attributes" "library" "id_prefix" "patron" Embed list sent as a request header

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Payload

Content type

application/json

{ }

<