openapi: 3.0.3 info: contact: name: Koha Development Team url: https://koha-community.org/ description: "## Background\n\nThe API supports two sets of endpoints, one targetted at library staff and the other at at library users.\n\nThose endpoints under the `/public` path are aimed at delivering functionality tailored to library users and offer\na more restricted set of functions, overrides and data in thier responses for data privacy and library policy\nreasons. Many of these endpoints do not require authentication for fetching public data, though an authenticated\nsession will expose additional options and allow users to see more data where it is part of their own record.\n\nAll other endpoints are targetted at the staff interface level and allow for additional functionality and a more\nunrestricted view of data. These endpoints, however, have a level of redaction built in for resources that the\napi consumer should not have access to. For example, user data for users who do not belong to the same library\nor library group of your api user will be reduced to just minimum neccesary for a valid response. Object keys will\nbe consistent for all responses, but their values may be removed depending on access.\n\n## Authentication\n\nThe API supports the following authentication mechanisms\n\n* HTTP Basic authentication\n* OAuth2 (client credentials grant)\n* Cookie-based\n\nBoth _Basic authentication_ and the _OAuth2_ flow, need to be enabled\nby system preferences.\n\n## Authorization\n\nThe API uses existing user profiles to restrict access to resources based on user permissions and the library the\nAPI user is assigned to. This may result, at times, in resources being returned in a redacted form with all keys\npresent but sensative values nulled.\n\nWe do not yet support OAuth Scopes or the Authorization Code grant flow.\n\n## Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call. The body of the response will be JSON in the following format:\n\n```\n{\n \"error\": \"Current settings prevent the passed due date to be applied\",\n \"error_code\": \"invalid_due_date\"\n}\n```\n\nNote: Some routes might offer additional attributes in their error responses but that\"s\nsubject to change and thus not documented.\n\n## Filtering responses\n\nThe API allows for some advanced response filtering using a JSON based query syntax. The\nquery can be added to the requests:\n\n* as a query parameter `q=`\n* in the request body\n\nFor simple field equality matches we can use `{ \"fieldname\": \"value\" }` where the fieldname\nmatches one of the fields as described in the particular endpoints response object.\n\nWe can refine that with more complex matching clauses by nesting a the clause into the\nobject; `{ \"fieldname\": { \"clause\": \"value\" } }`.\n\nAvailable matching clauses include `=`, `!=`, `<`, `>`, `<=`, `>=` and `-not`. We also support `-like`\nand `-not_like` string comparisons with `%` used to denote wildcards, thus you can pass\n`{ \"fieldname\": { \"-like\": \"value%\" } }` to do a 'starts with' string match for example.\n\nWe can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`\nlevel will result in an \"AND\" query, whilst combinding them in an `ARRAY` will result in an\n\"OR\" query: `{ \"field1\": \"value2\", \"field2\": \"value2\" }` will filter the response to only those\nresults with both field1 containing value2 AND field2 containing value2 for example.\n\nThere is a collection of special operators also available to you, including:\n\n* `-in` - Expects an array of values to perform an OR match against\n* `-not_in` - Expects an array of values to perform a NOR match against\n* `-between` - Expects two values which the value of the field is expected to fall between\n* `-not_between` - Expects two values which the value of the field is expected to fall outside of\n* `-ident` - Expects a second field name to match the two field values against\n* `-regexp` - Expects a perl compatible regular expression for which the value should match\n\nLogic and nesting is also supported and you may use `-and` and `-or` to change the logic of an ARRAY\nor HASH as described above.\n\nAdditionally, if you are requesting related data be embedded into the response one can query\non the related data using dot notation in the field names.\n\n### Examples\n\nThe following request would return any patron with firstname \"Henry\" and lastname \"Acevedo\";\n\n`curl -u koha:koha --request GET \"http://127.0.0.1:8081/api/v1/patrons/\" --data-raw '{ \"surname\": \"Acevedo\", \"firstname\": \"Henry\" }'`\n\nThe following request would return any patron whose lastname begins with \"Ace\";\n\n`curl -u koha:koha --request GET \"http://127.0.0.1:8081/api/v1/patrons/\" --data-raw '{ \"surname\": { \"-like\": \"Ace%\" }'`\n\nThe following request would return any patron whose lastname is \"Acevedo\" OR \"Bernardo\"\n\n`curl -u koha:koha --request GET \"http://127.0.0.1:8081/api/v1/patrons/\" --data-raw '{ \"surname\": [ \"Acevedo\", \"Bernardo\" ] }'`\n\nThe following request embeds the related patron extended attributes data and filters on it.\n\n`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\" }'`\n\n## Special headers\n\n### x-koha-embed\n\nThis optional header allows the api consumer to request additional related data\nto be returned in the api response. It also allows for cross referencing in the\nqueries as described above. It accepts a comma delimited list of relation names.\n\nRelations may on occasion also support dot delimited nesting to allow traversal.\n\n### x-koha-library\n\nThis optional header should be passed to give your api request a library\ncontext; If it is not included in the request, then the request context\nwill default to using your api comsumer\"s assigned home library.\n" license: name: GPL v3, url: http://www.gnu.org/licenses/gpl.txt title: Koha REST 2fa transfer_limits API version: '1' servers: - url: https://libserv.iitk.ac.in/api/v1 description: PKK Library Koha REST API (production) tags: - description: 'Manage transfer limits ' name: transfer_limits x-displayName: Transfer limits paths: /transfer_limits: get: tags: - transfer_limits summary: List transfer limits description: This resource returns a list of existing transfer limits. operationId: listTransferLimits parameters: - name: to_library_id in: query required: false description: Search on to_library_id schema: type: string - name: from_library_id in: query required: false description: Search on from_library_id schema: type: string - name: item_type in: query required: false description: Search on item_type schema: type: string - name: collection_code in: query required: false description: Search on collection_code schema: type: string - name: _match in: query required: false description: Matching criteria schema: type: string enum: - contains - exact - starts_with - ends_with - name: _order_by in: query required: false description: Sorting criteria schema: type: array items: type: string - name: _page in: query required: false description: Page number, for paginated object listing schema: type: integer - name: _per_page in: query required: false description: Page size, for paginated object listing schema: type: integer - name: q in: query required: false description: Query filter sent as a request parameter style: form explode: true schema: type: array items: type: string - name: x-koha-request-id in: header required: false description: Request id header schema: type: integer requestBody: required: false content: application/json: schema: type: object description: Query filter sent through request"s body responses: '200': description: A list of transfer limits content: application/json: schema: items: $ref: '#/components/schemas/transfer_limit_yaml' type: array '400': description: "Bad request. Possible `error_code` attribute values:\n\n * `invalid_query`\n" content: application/json: schema: $ref: '#/components/schemas/error_yaml' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/error_yaml' '403': description: Access forbidden content: application/json: schema: $ref: '#/components/schemas/error_yaml' '404': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '500': description: 'Internal server error. Possible `error_code` attribute values: * `internal_server_error` ' content: application/json: schema: $ref: '#/components/schemas/error_yaml' '501': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '503': description: Under maintenance content: application/json: schema: $ref: '#/components/schemas/error_yaml' post: tags: - transfer_limits summary: Add a transfer limit description: This resource accepts a new transfer limit and creates it if it does not already exist. operationId: addTransferLimit requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/transfer_limit_yaml' description: A JSON object containing information about a new transfer limit responses: '201': description: Transfer limit added content: application/json: schema: $ref: '#/components/schemas/transfer_limit_yaml' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/error_yaml' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/error_yaml' '403': description: Access forbidden content: application/json: schema: $ref: '#/components/schemas/error_yaml' '404': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '409': description: Conflict in creating resource content: application/json: schema: $ref: '#/components/schemas/error_yaml' '500': description: 'Internal server error. Possible `error_code` attribute values: * `internal_server_error` ' content: application/json: schema: $ref: '#/components/schemas/error_yaml' '501': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '503': description: Under maintenance content: application/json: schema: $ref: '#/components/schemas/error_yaml' /transfer_limits/batch: delete: tags: - transfer_limits summary: Batch delete transfer limits description: This endpoint works just like [the POST version](#op-post-transfer_limits-batch), except it deletes transfer in batch rather than creating them. operationId: batchDeleteTransferLimits requestBody: required: true content: application/json: schema: additionalProperties: false properties: collection_code: description: Authorized value for the collection code associated with this limit type: - string - 'null' from_library_id: description: Internal library id for which library the item is coming from type: string item_type: description: Itemtype defining the type for this limi type: - string - 'null' to_library_id: description: Internal library id for which library the item is going to type: string type: object description: A JSON object containing information about new transfer limits. responses: '204': description: Transfer limits deleted '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/error_yaml' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/error_yaml' '403': description: Access forbidden content: application/json: schema: $ref: '#/components/schemas/error_yaml' '404': description: Library not found content: application/json: schema: $ref: '#/components/schemas/error_yaml' '500': description: 'Internal server error. Possible `error_code` attribute values: * `internal_server_error` ' content: application/json: schema: $ref: '#/components/schemas/error_yaml' '501': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '503': description: Under maintenance content: application/json: schema: $ref: '#/components/schemas/error_yaml' post: tags: - transfer_limits summary: Batch add transfer limits description: "\nThis resource batch creates new transfer limits based on the given data.\nTransfer limits can be defined based on `collection_code` or `item_type`. The endpoint only accepts one at a time, and which one is used will depend on the value of the `BranchTransferLimitsType` system preference.\nFor example, if the paramters `to_library_id: 'BranchA'` and `item_type: 'BOOK'` are passed in new transfer limits for `BOOK`s will be created, with one transfer limit each for all the branches defined in Koha. Given 4 branches, 3 limits would be created:\n* to_library_id: 'BranchA', from_library_id: 'BranchB', item_type: 'BOOK' * to_library_id: 'BranchA', from_library_id: 'BranchC', item_type: 'BOOK' * to_library_id: 'BranchA', from_library_id: 'BranchD', item_type: 'BOOK'\n\nThe body of the query would look like\n``` {\n 'to_library_id': 'BranchA',\n 'item_type': 'BOOK'\n\n} ```\nAs another example, imagine we have an itemtype that is never supposed to be transferred to another library. If we call that itemtype `LOCAL_ONLY` we would need to just pass `item_type: 'LOCAL_ONLY'`, which would create transfer limits for all libraries, meaning those items would never be allowed to transfer to another library. The body of the query would look like\n``` {\n 'item_type': 'LOCAL_ONLY'\n} ```\n" operationId: batchAddTransferLimits requestBody: required: true content: application/json: schema: additionalProperties: false properties: collection_code: description: Authorized value for the collection code associated with this limit type: - string - 'null' from_library_id: description: Internal library id for which library the item is coming from type: string item_type: description: Itemtype defining the type for this limi type: - string - 'null' to_library_id: description: Internal library id for which library the item is going to type: string type: object description: A JSON object containing information about new transfer limits. responses: '201': description: A list of transfer limits content: application/json: schema: items: $ref: '#/components/schemas/transfer_limit_yaml' type: array '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/error_yaml' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/error_yaml' '403': description: Access forbidden content: application/json: schema: $ref: '#/components/schemas/error_yaml' '404': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '409': description: Conflict in creating resource content: application/json: schema: $ref: '#/components/schemas/error_yaml' '500': description: 'Internal server error. Possible `error_code` attribute values: * `internal_server_error` ' content: application/json: schema: $ref: '#/components/schemas/error_yaml' '501': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '503': description: Under maintenance content: application/json: schema: $ref: '#/components/schemas/error_yaml' /transfer_limits/{limit_id}: delete: tags: - transfer_limits summary: Delete transfer limit description: This resource deletes a transfer limit for the given limit id operationId: deleteTransferLimit parameters: - name: limit_id in: path required: true description: Internal transfer limit identifier schema: type: string responses: '204': description: Transfer limit deleted content: application/json: schema: type: string '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/error_yaml' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/error_yaml' '403': description: Access forbidden content: application/json: schema: $ref: '#/components/schemas/error_yaml' '404': description: Library not found content: application/json: schema: $ref: '#/components/schemas/error_yaml' '500': description: 'Internal server error. Possible `error_code` attribute values: * `internal_server_error` ' content: application/json: schema: $ref: '#/components/schemas/error_yaml' '501': description: Default response. content: application/json: schema: $ref: '#/components/schemas/DefaultResponse' '503': description: Under maintenance content: application/json: schema: $ref: '#/components/schemas/error_yaml' components: schemas: error_yaml: additionalProperties: true properties: error: description: Error message type: string error_code: description: Error code type: string type: object DefaultResponse: properties: errors: items: properties: message: type: string path: type: string required: - message type: object type: array required: - errors type: object transfer_limit_yaml: additionalProperties: false properties: collection_code: description: Authorized value for the collection code associated with this limit type: - string - 'null' from_library_id: description: Internal library id for which library the item is coming from type: string item_type: description: Itemtype defining the type for this limi type: - string - 'null' limit_id: description: Internal transfer limit identifier type: integer to_library_id: description: Internal library id for which library the item is going to type: string required: - to_library_id - from_library_id type: object