--- swagger: "2.0" basePath: /api/v1 definitions: account_line: $ref: ./definitions/account_line.yaml advancededitormacro: $ref: ./definitions/advancededitormacro.yaml allows_renewal: $ref: ./definitions/allows_renewal.yaml basket: $ref: ./definitions/basket.yaml cashup: $ref: ./definitions/cashup.yaml checkout: $ref: ./definitions/checkout.yaml checkouts: $ref: ./definitions/checkouts.yaml circ-rule-kind: $ref: ./definitions/circ-rule-kind.yaml city: $ref: ./definitions/city.yaml error: $ref: ./definitions/error.yaml fund: $ref: ./definitions/fund.yaml hold: $ref: ./definitions/hold.yaml holds: $ref: ./definitions/holds.yaml ill_backend: $ref: ./definitions/ill_backend.yaml ill_backends: $ref: ./definitions/ill_backends.yaml import_batch_profile: $ref: ./definitions/import_batch_profile.yaml import_batch_profiles: $ref: ./definitions/import_batch_profiles.yaml import_record_match: $ref: ./definitions/import_record_match.yaml invoice: $ref: ./definitions/invoice.yaml item: $ref: ./definitions/item.yaml library: $ref: ./definitions/library.yaml order: $ref: ./definitions/order.yaml patron: $ref: ./definitions/patron.yaml patron_account_credit: $ref: ./definitions/patron_account_credit.yaml patron_balance: $ref: ./definitions/patron_balance.yaml patron_extended_attribute: $ref: ./definitions/patron_extended_attribute.yaml quote: $ref: ./definitions/quote.yaml return_claim: $ref: ./definitions/return_claim.yaml smtp_server: $ref: ./definitions/smtp_server.yaml suggestion: $ref: ./definitions/suggestion.yaml transfer_limit: $ref: ./definitions/transfer_limit.yaml vendor: $ref: ./definitions/vendor.yaml paths: /acquisitions/baskets/managers: $ref: paths/acquisitions_baskets.yaml#/~1acquisitions~1baskets~1managers /acquisitions/funds: $ref: ./paths/acquisitions_funds.yaml#/~1acquisitions~1funds /acquisitions/funds/owners: $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds~1owners /acquisitions/funds/users: $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds~1users /acquisitions/orders: $ref: ./paths/acquisitions_orders.yaml#/~1acquisitions~1orders "/acquisitions/orders/{order_id}": $ref: "./paths/acquisitions_orders.yaml#/~1acquisitions~1orders~1{order_id}" /acquisitions/vendors: $ref: ./paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors "/acquisitions/vendors/{vendor_id}": $ref: "./paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors~1{vendor_id}" /advanced_editor/macros: $ref: ./paths/advancededitormacros.yaml#/~1advanced_editor~1macros /advanced_editor/macros/shared: $ref: ./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared "/advanced_editor/macros/shared/{advancededitormacro_id}": $ref: "./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared~1{advancededitormacro_id}" "/advanced_editor/macros/{advancededitormacro_id}": $ref: "./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1{advancededitormacro_id}" "/article_requests/{article_request_id}": $ref: "./paths/article_requests.yaml#/~1article_requests~1{article_request_id}" "/biblios/{biblio_id}": $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}" "/biblios/{biblio_id}/checkouts": $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1checkouts" "/biblios/{biblio_id}/items": $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1items" "/biblios/{biblio_id}/pickup_locations": $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1pickup_locations" "/cash_registers/{cash_register_id}/cashups": $ref: "./paths/cash_registers.yaml#/~1cash_registers~1{cash_register_id}~1cashups" "/cashups/{cashup_id}": $ref: "./paths/cash_registers.yaml#/~1cashups~1{cashup_id}" /checkouts: $ref: ./paths/checkouts.yaml#/~1checkouts "/checkouts/{checkout_id}": $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}" "/checkouts/{checkout_id}/allows_renewal": $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1allows_renewal" "/checkouts/{checkout_id}/renewal": $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal" /circulation-rules/kinds: $ref: ./paths/circulation-rules.yaml#/~1circulation-rules~1kinds /cities: $ref: ./paths/cities.yaml#/~1cities "/cities/{city_id}": $ref: "./paths/cities.yaml#/~1cities~1{city_id}" "/clubs/{club_id}/holds": $ref: "./paths/clubs.yaml#/~1clubs~1{club_id}~1holds" /config/smtp_servers: $ref: ./paths/config_smtp_servers.yaml#/~1config~1smtp_servers "/config/smtp_servers/{smtp_server_id}": $ref: "./paths/config_smtp_servers.yaml#/~1config~1smtp_servers~1{smtp_server_id}" /holds: $ref: ./paths/holds.yaml#/~1holds "/holds/{hold_id}": $ref: "./paths/holds.yaml#/~1holds~1{hold_id}" "/holds/{hold_id}/pickup_location": $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1pickup_location" "/holds/{hold_id}/pickup_locations": $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1pickup_locations" "/holds/{hold_id}/priority": $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1priority" "/holds/{hold_id}/suspension": $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1suspension" /ill_backends: $ref: ./paths/ill_backends.yaml#/~1ill_backends "/ill_backends/{ill_backend_id}": $ref: "./paths/ill_backends.yaml#/~1ill_backends~1{ill_backend_id}" /illrequests: $ref: ./paths/illrequests.yaml#/~1illrequests "/import/{import_batch_id}/records/{import_record_id}/matches/chosen": $ref: "./paths/import_record_matches.yaml#/~1import~1{import_batch_id}~1records~1{import_record_id}~1matches~1chosen" /import_batch_profiles: $ref: ./paths/import_batch_profiles.yaml#/~1import_batch_profiles "/import_batch_profiles/{import_batch_profile_id}": $ref: "./paths/import_batch_profiles.yaml#/~1import_batch_profiles~1{import_batch_profile_id}" /items: $ref: ./paths/items.yaml#/~1items "/items/{item_id}": $ref: "./paths/items.yaml#/~1items~1{item_id}" "/items/{item_id}/pickup_locations": $ref: "./paths/items.yaml#/~1items~1{item_id}~1pickup_locations" /libraries: $ref: ./paths/libraries.yaml#/~1libraries "/libraries/{library_id}": $ref: "./paths/libraries.yaml#/~1libraries~1{library_id}" /oauth/token: $ref: ./paths/oauth.yaml#/~1oauth~1token /patrons: $ref: ./paths/patrons.yaml#/~1patrons "/patrons/{patron_id}": $ref: "./paths/patrons.yaml#/~1patrons~1{patron_id}" "/patrons/{patron_id}/account": $ref: "./paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account" "/patrons/{patron_id}/account/credits": $ref: "./paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account~1credits" "/patrons/{patron_id}/extended_attributes": $ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes" "/patrons/{patron_id}/extended_attributes/{extended_attribute_id}": $ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id}" "/patrons/{patron_id}/holds": $ref: "./paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds" "/patrons/{patron_id}/password": $ref: "./paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password" "/public/biblios/{biblio_id}": $ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}" "/public/biblios/{biblio_id}/items": $ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items" /public/libraries: $ref: ./paths/libraries.yaml#/~1public~1libraries "/public/libraries/{library_id}": $ref: "./paths/libraries.yaml#/~1public~1libraries~1{library_id}" "/public/patrons/{patron_id}/article_requests/{article_request_id}": $ref: "./paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id}" "/public/patrons/{patron_id}/guarantors/can_see_charges": $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_charges" "/public/patrons/{patron_id}/guarantors/can_see_checkouts": $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts" "/public/patrons/{patron_id}/password": $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password" /quotes: $ref: ./paths/quotes.yaml#/~1quotes "/quotes/{quote_id}": $ref: "./paths/quotes.yaml#/~1quotes~1{quote_id}" /return_claims: $ref: ./paths/return_claims.yaml#/~1return_claims "/return_claims/{claim_id}": $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}" "/return_claims/{claim_id}/notes": $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1notes" "/return_claims/{claim_id}/resolve": $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1resolve" "/rotas/{rota_id}/stages/{stage_id}/position": $ref: "./paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position" /suggestions: $ref: ./paths/suggestions.yaml#/~1suggestions "/suggestions/{suggestion_id}": $ref: "./paths/suggestions.yaml#/~1suggestions~1{suggestion_id}" /suggestions/managers: $ref: paths/suggestions.yaml#/~1suggestions~1managers /transfer_limits: $ref: ./paths/transfer_limits.yaml#/~1transfer_limits /transfer_limits/batch: $ref: ./paths/transfer_limits.yaml#/~1transfer_limits~1batch "/transfer_limits/{limit_id}": $ref: "./paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id}" parameters: advancededitormacro_id_pp: description: Advanced editor macro internal identifier in: path name: advancededitormacro_id required: true type: integer biblio_id_pp: description: Record internal identifier in: path name: biblio_id required: true type: integer candidate_match_id_pp: description: Internal import record match identifier in: path name: candidate_match_id required: true type: integer cash_register_id_pp: description: Cash register internal identifier in: path name: cash_register_id required: true type: integer cashup_id_pp: description: Cashup internal identifier in: path name: cashup_id required: true type: integer checkout_id_pp: description: Internal checkout identifier in: path name: checkout_id required: true type: integer city_id_pp: description: City internal identifier in: path name: city_id required: true type: integer club_id_pp: description: Internal club identifier in: path name: club_id required: true type: integer fund_id_pp: description: Fund id in: path name: fund_id required: true type: integer hold_id_pp: description: Internal hold identifier in: path name: hold_id required: true type: integer import_batch_profile_id_pp: description: Internal profile identifier in: path name: import_batch_profile_id required: true type: integer import_record_id_pp: description: Internal import record identifier in: path name: import_record_id required: true type: integer item_id_pp: description: Internal item identifier in: path name: item_id required: true type: integer library_id_pp: description: Internal library identifier in: path name: library_id required: true type: string match: description: Matching criteria enum: - contains - exact - starts_with - ends_with in: query name: _match required: false type: string order_by: collectionFormat: csv description: Sorting criteria in: query items: type: string name: _order_by required: false type: array order_id_pp: description: Internal order identifier in: path name: order_id required: true type: integer page: description: "Page number, for paginated object listing" in: query name: _page required: false type: integer patron_id_pp: description: Internal patron identifier in: path name: patron_id required: true type: integer patron_id_qp: description: Internal patron identifier in: query name: patron_id type: integer per_page: description: "Page size, for paginated object listing" in: query name: _per_page required: false type: integer q_body: description: Query filter sent through request"s body in: body name: query required: false schema: type: object q_header: description: Query filter sent as a request header in: header name: x-koha-query required: false type: string q_param: description: Query filter sent as a request parameter in: query name: q required: false type: array items: type: string collectionFormat: multi quote_id_pp: description: Quote internal identifier in: path name: quote_id required: true type: integer request_id_header: description: Request id header in: header name: x-koha-request-id required: false type: integer seen_pp: description: Item was seen flag in: query name: seen required: false type: integer smtp_server_id_pp: description: SMTP server internal identifier in: path name: smtp_server_id required: true type: integer suggestion_id_pp: description: Internal suggestion identifier in: path name: suggestion_id required: true type: integer transfer_limit_id_pp: description: Internal transfer limit identifier in: path name: limit_id required: true type: string vendor_id_pp: description: Vendor id in: path name: vendor_id required: true type: integer info: title: Koha REST API version: "1" license: name: "GPL v3," url: http://www.gnu.org/licenses/gpl.txt contact: name: Koha Development Team url: https://koha-community.org/ description: | ## 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. tags: - description: "Manage article requests\n" name: article_requests x-displayName: Article requests - description: "Manage bibliographic records\n" name: biblios x-displayName: Biblios - description: "Manage cash register cashups\n" name: cashups x-displayName: Cashups - description: "Manage checkouts\n" name: checkouts x-displayName: Checkouts - description: "Manage circulation rules\n" name: circulation_rules x-displayName: Circulation rules - description: "Manage cities\n" name: cities x-displayName: Cities - description: "Manage patron clubs\n" name: clubs x-displayName: Clubs - description: "Manage funds for the acquisitions module\n" name: funds x-displayName: Funds - description: "Manage holds\n" name: holds x-displayName: Holds - description: "Manage ILL module backends\n" name: illbackends x-displayName: ILL backends - description: "Manage ILL requests\n" name: illrequests x-displayName: ILL requests - description: "Manage items\n" name: items x-displayName: Items - description: "Manage libraries\n" name: libraries x-displayName: Libraries - description: "Manage macros\n" name: macros x-displayName: Macros - description: "Manage acquisition orders\n" name: orders x-displayName: Orders - description: "Handle OAuth flows\n" name: oauth x-displayName: OAuth - description: "Manage patrons\n" name: patrons x-displayName: Patrons - description: "Manage quotes\n" name: quotes x-displayName: Quotes - description: "Manage return claims\n" name: return_claims x-displayName: Return claims - description: "Manage rotas\n" name: rotas x-displayName: Rotas - description: "Manage SMTP servers configurations\n" name: smtp_servers x-displayName: SMTP servers - description: "Manage transfer limits\n" name: transfer x-displayName: Transfer limits - description: "Manage purchase suggestions\n" name: suggestions x-displayName: Purchase suggestions - description: "Manage vendors for the acquisitions module\n" name: vendors x-displayName: Vendors - description: "Manage batch import profiles\n" name: batch_import_profiles x-displayName: Batch import profiles