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

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

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

Generate a secret

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

Responses

Response samples

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

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "protocol": "OAuth",
  • "mapping": { },
  • "matchpoint": "email",
  • "config": { },
  • "icon_url": "string",
  • "domains": [
    ]
}

Response samples

Content type
application/json
{
  • "identity_provider_id": 0,
  • "code": "string",
  • "description": "string",
  • "protocol": "OAuth",
  • "mapping": { },
  • "matchpoint": "email",
  • "config": { },
  • "icon_url": "string",
  • "domains": [
    ]
}

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

Content type
application/json
{
  • "identity_provider_id": 0,
  • "code": "string",
  • "description": "string",
  • "protocol": "OAuth",
  • "mapping": { },
  • "matchpoint": "email",
  • "config": { },
  • "icon_url": "string",
  • "domains": [
    ]
}

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

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "protocol": "OAuth",
  • "mapping": { },
  • "matchpoint": "email",
  • "config": { },
  • "icon_url": "string",
  • "domains": [
    ]
}

Response samples

Content type
application/json
{
  • "identity_provider_id": 0,
  • "code": "string",
  • "description": "string",
  • "protocol": "OAuth",
  • "mapping": { },
  • "matchpoint": "email",
  • "config": { },
  • "icon_url": "string",
  • "domains": [
    ]
}

Delete authentication provider

koha-authorization: {"permissions":{"parameters":"manage_identity_providers"}}
path Parameters
identity_provider_id
required
integer

Authentication provider internal identifier

Responses

Response samples

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

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

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

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

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

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

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

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

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

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)

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",
  • "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",
  • "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)

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",
  • "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",
  • "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

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

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

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

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

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

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

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

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

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

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

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

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

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

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

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

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

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

ILL backends

Manage ILL module backends

List ILL backends

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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": [
    ]
}

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

Content type
application/json
{ }
<