---
swagger: "2.0"
basePath: /api/v1
paths:
  $ref: paths.yaml
definitions:
  $ref: definitions.yaml
parameters:
  $ref: parameters.yaml
x-primitives:
  $ref: x-primitives.yaml
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.

    ### 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 whilse 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" ] }'`

    ## Special headers

    ### 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:
  - name: "article_requests"
    x-displayName: Article requests
    description: |
      Manage article requests
  - name: "biblios"
    x-displayName: Biblios
    description: |
      Manage bibliographic records
  - name: "cashups"
    x-displayName: Cashups
    description: |
      Manage cash register cashups
  - name: "checkouts"
    x-displayName: Checkouts
    description: |
      Manage checkouts
  - name: "circulation_rules"
    x-displayName: Circulation rules
    description: |
      Manage circulation rules
  - name: "cities"
    x-displayName: Cities
    description: |
      Manage cities
  - name: "clubs"
    x-displayName: Clubs
    description: |
      Manage patron clubs
  - name: "funds"
    x-displayName: Funds
    description: |
      Manage funds for the acquisitions module
  - name: "holds"
    x-displayName: Holds
    description: |
      Manage holds
  - name: "illbackends"
    x-displayName: ILL backends
    description: |
      Manage ILL module backends
  - name: "illrequests"
    x-displayName: ILL requests
    description: |
      Manage ILL requests
  - name: "items"
    x-displayName: Items
    description: |
      Manage items
  - name: "libraries"
    x-displayName: Libraries
    description: |
      Manage libraries
  - name: "macros"
    x-displayName: Macros
    description: |
      Manage macros
  - name: "orders"
    x-displayName: Orders
    description: |
      Manage acquisition orders
  - name: "oauth"
    x-displayName: "OAuth"
    description: |
      Handle OAuth flows
  - name: "patrons"
    x-displayName: Patrons
    description: |
      Manage patrons
  - name: "quotes"
    x-displayName: Quotes
    description: |
      Manage quotes
  - name: "return_claims"
    x-displayName: Return claims
    description: |
      Manage return claims
  - name: "rotas"
    x-displayName: Rotas
    description: |
      Manage rotas
  - name: "smtp_servers"
    x-displayName: SMTP servers
    description: |
      Manage SMTP servers configurations
  - name: "transfer"
    x-displayName: Transfer limits
    description: |
      Manage transfer limits
  - name: "suggestions"
    x-displayName: "Purchase suggestions"
    description: |
      Manage purchase suggestions
  - name: "vendors"
    x-displayName: "Vendors"
    description: |
      Manage vendors for the acquisitions module
  - name: "batch_import_profiles"
    x-displayName: Batch import profiles
    description: |
      Manage batch import profiles