22.11 22.05 21.11 21.05 20.11 20.05 19.11 Development
Documentation Powered by ReDoc

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

Responses

Response samples

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

Generate a secret

Responses

Response samples

Content type
application/json
{
  • "secret32": "string",
  • "qr_code": "string",
  • "issuer": "string",
  • "key_id": "string"
}

Verify two-factor registration

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

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

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

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

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 Nullable

Attribute mapping

matchpoint
string
Enum: "email" "userid" "cardnumber"

Patron attribute that will be used to match

config
required
object

Configuration

icon_url
string Nullable

Icon url

domains
Array of any Nullable

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

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

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 Nullable

Attribute mapping

matchpoint
string
Enum: "email" "userid" "cardnumber"

Patron attribute that will be used to match

config
required
object

Configuration

icon_url
string Nullable

Icon url

domains
Array of any Nullable

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

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

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

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 Nullable

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 Nullable

Internal identifier for the default library to be assigned to the new patrons

default_category_id
required
string Nullable

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

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

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 Nullable

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 Nullable

Internal identifier for the default library to be assigned to the new patrons

default_category_id
required
string Nullable

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

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

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
[
  • {
    }
]

Biblios

Manage bibliographic records

Get biblio

path Parameters
biblio_id
required
integer

Record internal identifier

Responses

Response samples

Content type
application/json
application/json
application/marcxml+xml
application/marc-in-json
application/marc
text/plain
{
  • "error": "string",
  • "error_code": "string"
}

Delete biblio

path Parameters
biblio_id
required
integer

Record internal identifier

Responses

Response samples

Content type
application/json
"string"

Get items for a biblio

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
[
  • {
    }
]

Get valid pickup locations for a biblio

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
application/marcxml+xml
application/marcxml+xml
application/marc-in-json
application/marc
text/plain
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

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 Nullable

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

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

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

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

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

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

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

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

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

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

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

Request Body schema: application/json

A JSON object containing informations about the new hold

name
required
string

city name

state
required
string Nullable

city state

postal_code
required
string Nullable

city postal code

country
required
string Nullable

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

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

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 Nullable

city state

postal_code
required
string Nullable

city postal code

country
required
string Nullable

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

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

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 Nullable

Internal biblio identifier

item_id
integer Nullable

Internal item identifier

pickup_library_id
required
string

Internal library identifier for the pickup library

expiration_date
string <date> Nullable

Hold end date

notes
string Nullable

Notes related to this hold

item_type
string Nullable

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

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

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

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

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

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 Nullable

Internal biblio identifier

item_group_id
integer Nullable

Internal item group identifier

hold_date
string <date> Nullable

The date the hold was placed

item_id
integer Nullable

Internal item identifier

pickup_library_id
required
string

Internal library identifier for the pickup library

expiration_date
string <date> Nullable

Hold end date

notes
string Nullable

Notes related to this hold

item_type
string Nullable

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

non_priority
boolean Nullable

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

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.

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

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

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

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

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

Response samples

Content type
application/json
0

Suspend the hold

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

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get ILL backend

path Parameters
ill_backend_id
required
string

ILL backend id/name

Responses

Response samples

Content type
application/json
{
  • "ill_backend_id": "string",
  • "capabilities": { }
}

ILL requests

Manage ILL requests

List ILL requests

query Parameters
embed
Array of strings
Items Enum: "patron" "library" "capabilities" "metadata" "requested_partners" "comments" "status_alias"

Additional objects that should be embedded in the response

backend
string

The name of a ILL backend

orderid
string

The order ID of a request

biblionumber
integer

Internal biblio identifier

borrowernumber
integer

Internal patron identifier

completed
string

The date the request was considered completed

completed_formatted
string

The date the request was considered complete formatted

status
string

A full status string e.g. REQREV

cost
number

The quoted cost of the request

price_paid
number

The final cost of the request

medium
string

The medium of the requested item

updated
string

The last updated date of the request

updated_formatted
string

The last updated date of the request formatted

placed
string

The date the request was placed

placed_formatted
string

The date the request was placed formatted

branchcode
string

Library ID

Responses

Response samples

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

import_batches

Manage import batches

Set the chosen match for an import record ID

path Parameters
import_batch_id
required
integer

An import_batch ID

import_record_id
required
integer

An import_record ID

Request Body schema: application/json

A JSON object containing fields to modify

candidate_match_id
integer

Candidate match to choose

Responses

Request samples

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

Response samples

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

Unset the chosen match for an import record ID

path Parameters
import_batch_id
required
integer

An import_batch ID

import_record_id
required
integer

An import_record ID

Responses

Response samples

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

Item groups

Manage item groups

List item_groups

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

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

Request Body schema: application/json

Query filter sent through request"s body

object

Responses

Request samples

Content type
application/json
{ }

Add item group

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

Request Body schema: application/json

A JSON object representing an item group

description
string

ItemGroup description

display_order
integer

Position in waiting queue

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "display_order": 0
}

Get item group

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

item_group_id
required
string

Internal identifier for the item_group

Responses

Update item group

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

item_group_id
required
string

Internal identifier for the item group

Request Body schema: application/json

A JSON object with the new values for the item group

description
string

ItemGroup description

display_order
integer

Position in waiting queue

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "display_order": 0
}

Delete item group

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

item_group_id
required
string

Internal identifier for the item group

Responses

Add item to item group

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

item_group_id
required
string

Internal identifier for the item group

Request Body schema: application/json

A JSON object containing an item_id

item_id
integer

Internal identifier for an item to be linked

Responses

Request samples

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

Delete item from item group

path Parameters
biblio_id
required
string

Internal identifier for the parent bibliographic record

item_group_id
required
string

Internal identifier for the item group

item_id
required
string

Internal identifier for the item

Responses

Items

Manage items

List items

query Parameters
external_id
string

Search on the item's barcode

_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
[
  • {
    }
]

Get item

path Parameters
item_id
required
integer

Internal item identifier

Responses

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

Add item to bundle

path Parameters
item_id
required
integer

Internal item identifier

Request Body schema: application/json

A JSON object containing information about the new bundle link

item_id
integer Nullable

Internal item identifier

external_id
string Nullable

Item barcode

Responses

Request samples

Content type
application/json
{
  • "item_id": 0,
  • "external_id": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

List bundled items

path Parameters
item_id
required
integer

Internal item identifier

query Parameters
external_id
string

Search on the item's barcode

_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
[
  • {
    }
]

Remove item from bundle

path Parameters
item_id
required
integer

Internal item identifier

bundled_item_id
required
string

Internal identifier for the bundled item

Responses

Response samples

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

Get valid pickup locations for an item

path Parameters
item_id
required
integer

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

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
[
  • {
    }
]

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

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
[
  • {
    }
]

Jobs

Manage jobs

List jobs

query Parameters
only_current
boolean

Only include current jobs

_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
[
  • {
    }
]

Get a job

path Parameters
job_id
required
integer

Job internal identifier

Responses

Response samples

Content type
application/json
{
  • "job_id": 0,
  • "status": "string",
  • "progress": "string",
  • "size": "string",
  • "patron_id": "string",
  • "type": "string",
  • "queue": "string",
  • "data": { },
  • "context": { },
  • "enqueued_date": "2019-08-24T14:15:22Z",
  • "started_date": "2019-08-24T14:15:22Z",
  • "ended_date": "2019-08-24T14:15:22Z"
}

Libraries

Manage libraries

List libraries

query Parameters
name
string

Case insensitive 'starts-with' search on name

address1
string

Case insensitive 'starts-with' search on address1

address2
string

Case insensitive 'starts-with' search on address2

address3
string

Case insensitive 'starts-with' search on address3

postal_code
string

Case insensitive 'starts-with' search on postal code

city
string

Case insensitive 'starts-with' search on city

state
string

Case insensitive 'starts-with' search on state

country
string

Case insensitive 'starts_with' search on country

phone
string

Case insensitive 'starts_with' search on phone number

fax
string

Case insensitive 'starts_with' search on fax number

email
string

Case insensitive 'starts_with' search on email address

reply_to_email
string

Case insensitive 'starts_with' search on Reply-To email address

return_path_email
string

Case insensitive 'starts_with' search on Return-Path email address

url
string

Case insensitive 'starts_with' search on website URL

ip
string

Case insensitive 'starts_with' search on IP address

notes
string

Case insensitive 'starts_with' search on notes

_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: "smtp_server"

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
[
  • {
    }
]</