> ## Documentation Index > Fetch the complete documentation index at: https://docs.isaacus.com/llms.txt > Use this file to discover all available pages before exploring further. # Extractive question answering > Extract information from documents with an Isaacus extractive question answering model. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/isaacus/openapi.documented.yml post /extractions/qa openapi: 3.1.0 info: title: Isaacus API version: 0.8.2 description: A RESTful API for using Isaacus legal models, data and other solutions. termsOfService: https://isaacus.com/terms contact: name: Isaacus Support url: https://isaacus.com/support email: support@isaacus.com license: name: Apache 2.0 url: https://github.com/isaacus-dev/openapi/blob/main/LICENSE servers: - url: https://api.isaacus.com/v1 security: - APIKeyBearerTokenAuth: [] tags: - name: Enrichments description: Enrich documents with an Isaacus enrichment model. - name: Embeddings description: Vectorize content with an Isaacus embedding model. - name: Rerankings description: >- Score and rank documents by their relevance to queries with an Isaacus reranker. - name: Extractions description: Extract information from documents with an Isaacus extraction model. - name: Classifications description: Classify documents with an Isaacus classification model. externalDocs: url: https://docs.isaacus.com/api-reference description: Reference documentation for the Isaacus API. paths: /extractions/qa: post: tags: - Extractions summary: Extractive question answering description: >- Extract information from documents with an Isaacus extractive question answering model. operationId: CreateAnswerExtractions requestBody: content: application/json: schema: $ref: '#/components/schemas/AnswerExtractionRequest' required: true responses: '200': description: The results of extracting answers from texts. content: application/json: schema: $ref: '#/components/schemas/AnswerExtractionResponse' examples: example: value: extractions: - index: 0 answers: - text: >- 30 years if the person murdered was a police officer and 25 years in any other case start: 61 end: 144 score: 0.11460486645671249 inextractability_score: 0.0027424068182309302 usage: input_tokens: 43 '400': description: The request was invalid or could not be processed. content: application/problem+json: schema: $ref: '#/components/schemas/ValidationError' examples: Validation error: summary: Validation error value: type: >- https://docs.isaacus.com/api-reference/errors#400-validation-error title: Validation error status: 400 detail: The request was invalid or could not be processed. instance: null Query too long error: summary: Query too long error value: type: >- https://docs.isaacus.com/api-reference/errors#400-validation-error title: Query too long error status: 400 detail: >- The provided query exceeds the model's maximum input length less overhead. instance: null '401': description: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. content: application/problem+json: schema: $ref: '#/components/schemas/UnauthorizedAPIKeyError' examples: Unauthorized API key error: summary: Unauthorized API key error value: type: >- https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: Unauthorized API key error status: 401 detail: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. instance: null Incorrect API key error: summary: Incorrect API key error value: type: >- https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: Incorrect API key error status: 401 detail: >- The API key you provided does not exist or is expired or revoked. instance: null '402': description: >- Your account is overdue, please pay any outstanding invoices to continue using our services. content: application/problem+json: schema: $ref: '#/components/schemas/AccountOverdueError' examples: Account overdue error: summary: Account overdue error value: type: >- https://docs.isaacus.com/api-reference/errors#402-payment-required title: Account overdue error status: 402 detail: >- Your account is overdue, please pay any outstanding invoices to continue using our services. instance: null '403': description: You are not allowed to access this resource. content: application/problem+json: schema: $ref: '#/components/schemas/AccessForbiddenError' examples: Access forbidden error: summary: Access forbidden error value: type: >- https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: Access forbidden error status: 403 detail: You are not allowed to access this resource. instance: null No subscription error: summary: No subscription error value: type: >- https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: No subscription error status: 403 detail: >- You do not have an active subscription to our zero-flat fee, usage-based API plan. instance: null '413': description: The request is larger than the server is willing or able to process. content: application/problem+json: schema: $ref: '#/components/schemas/RequestTooLargeError' examples: Request too large error: summary: Request too large error value: type: >- https://docs.isaacus.com/api-reference/errors#413-request-too-large title: Request too large error status: 413 detail: >- The request is larger than the server is willing or able to process. instance: null '500': description: An unexpected error occurred while processing the request. content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerError' examples: Internal server error: summary: Internal server error value: type: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: Internal server error status: 500 detail: An unexpected error occurred while processing the request. instance: null Chunking timeout error: summary: Chunking timeout error value: type: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: Chunking timeout error status: 500 detail: >- Chunking timed out. Did you try to chunk a very large text with a very low chunk size or very little variation in levels of whitespace? instance: null deprecated: false x-codeSamples: - lang: JavaScript source: >- import Isaacus from 'isaacus'; const client = new Isaacus({ apiKey: process.env['ISAACUS_API_KEY'], // This is the default and can be omitted }); const answerExtractionResponse = await client.extractions.qa.create({ model: 'kanon-answer-extractor', query: 'What is the punishment for murder in Victoria?', texts: [ 'The standard sentence for murder in the State of Victoria is 30 years if the person murdered was a police officer and 25 years in any other case.', ], }); console.log(answerExtractionResponse.extractions); - lang: Python source: |- import os from isaacus import Isaacus client = Isaacus( api_key=os.environ.get("ISAACUS_API_KEY"), # This is the default and can be omitted ) answer_extraction_response = client.extractions.qa.create( model="kanon-answer-extractor", query="What is the punishment for murder in Victoria?", texts=["The standard sentence for murder in the State of Victoria is 30 years if the person murdered was a police officer and 25 years in any other case."], ) print(answer_extraction_response.extractions) components: schemas: AnswerExtractionRequest: properties: model: type: string const: kanon-answer-extractor description: >- The ID of the [model](https://docs.isaacus.com/models#extractive-question-answering) to use for extractive question answering. examples: - kanon-answer-extractor query: type: string maxLength: 10000000 minLength: 1 pattern: \S description: >- The query to extract the answer to. The query must contain at least one non-whitespace character. Unlike the texts from which the answer will be extracted, the query cannot be so long that it exceeds the maximum input length of the model. examples: - What is the punishment for murder in Victoria? texts: items: type: string type: array description: |- The texts to search for the answer in and extract the answer from. There must be at least one text. Each text must contain at least one non-whitespace character. examples: - - >- The standard sentence for murder in the State of Victoria is 30 years if the person murdered was a police officer and 25 years in any other case. ignore_inextractability: type: boolean description: >- Whether to, if the model's score of the likelihood that an answer can not be extracted from a text is greater than the highest score of all possible answers, still return the highest scoring answers for that text. If you have already determined that the texts answer the query, for example, by using one of our classification or reranker models, then you should set this to `true`. default: false examples: - false top_k: type: integer minimum: 1 title: Positive integer description: |- The number of highest scoring answers to return. If `null`, which is the default, all answers will be returned. default: 1 examples: - 1 chunking_options: oneOf: - $ref: '#/components/schemas/ChunkingOptions' - type: 'null' description: >- Settings for how texts should be chunked into smaller segments by [semchunk](https://github.com/isaacus-dev/semchunk) before extraction. If `null`, the texts will not be chunked and will instead be truncated to the maximum input length of the model less overhead if found to exceed that limit. Chunking is enabled by default. examples: - size: null overlap_ratio: null overlap_tokens: null type: object required: - model - query - texts title: Answer extraction request description: >- A request to extract answers from documents with an Isaacus extractive question answering model. examples: - model: kanon-answer-extractor query: What is the punishment for murder in Victoria? texts: - >- The standard sentence for murder in the State of Victoria is 30 years if the person murdered was a police officer and 25 years in any other case. AnswerExtractionResponse: properties: extractions: items: $ref: '#/components/schemas/AnswerExtraction' type: array description: >- The results of extracting answers from the texts, ordered from highest to lowest answer confidence score (or else lowest to highest inextractability score if there are no answers for a text). examples: - - index: 0 answers: - text: >- 30 years if the person murdered was a police officer and 25 years in any other case start: 61 end: 144 score: 0.11460486645671249 inextractability_score: 0.0027424068182309302 usage: $ref: '#/components/schemas/AnswerExtractionUsage' type: object required: - extractions - usage title: Answer extraction response examples: - extractions: - index: 0 answers: - text: >- 30 years if the person murdered was a police officer and 25 years in any other case start: 61 end: 144 score: 0.11460486645671249 inextractability_score: 0.0027424068182309302 usage: input_tokens: 43 ValidationError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#400-validation-error examples: - https://docs.isaacus.com/api-reference/errors#400-validation-error title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Validation error examples: - Validation error status: type: integer const: 400 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 400 examples: - 400 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: The request was invalid or could not be processed. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: The request was invalid or could not be processed. examples: - The request was invalid or could not be processed. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Validation error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#400-validation-error title: Validation error status: 400 detail: The request was invalid or could not be processed. instance: null UnauthorizedAPIKeyError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#401-not-authenticated examples: - >- https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Unauthorized API key error examples: - Unauthorized API key error status: type: integer const: 401 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 401 examples: - 401 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. examples: - >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Unauthorized API key error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: Unauthorized API key error status: 401 detail: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. instance: null AccountOverdueError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#402-payment-required examples: - https://docs.isaacus.com/api-reference/errors#402-payment-required title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Account overdue error examples: - Account overdue error status: type: integer const: 402 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 402 examples: - 402 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: >- Your account is overdue, please pay any outstanding invoices to continue using our services. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: >- Your account is overdue, please pay any outstanding invoices to continue using our services. examples: - >- Your account is overdue, please pay any outstanding invoices to continue using our services. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Account overdue error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#402-payment-required title: Account overdue error status: 402 detail: >- Your account is overdue, please pay any outstanding invoices to continue using our services. instance: null AccessForbiddenError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#403-access-forbidden examples: - https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Access forbidden error examples: - Access forbidden error status: type: integer const: 403 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 403 examples: - 403 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: You are not allowed to access this resource. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: You are not allowed to access this resource. examples: - You are not allowed to access this resource. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Access forbidden error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: Access forbidden error status: 403 detail: You are not allowed to access this resource. instance: null RequestTooLargeError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#413-request-too-large examples: - >- https://docs.isaacus.com/api-reference/errors#413-request-too-large title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Request too large error examples: - Request too large error status: type: integer const: 413 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 413 examples: - 413 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: >- The request is larger than the server is willing or able to process. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: The request is larger than the server is willing or able to process. examples: - >- The request is larger than the server is willing or able to process. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Request too large error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#413-request-too-large title: Request too large error status: 413 detail: The request is larger than the server is willing or able to process. instance: null InternalServerError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error examples: - >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Internal server error examples: - Internal server error status: type: integer const: 500 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 500 examples: - 500 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: An unexpected error occurred while processing the request. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: An unexpected error occurred while processing the request. examples: - An unexpected error occurred while processing the request. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Internal server error description: An RFC 7807 problem detail object. examples: - type: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: Internal server error status: 500 detail: An unexpected error occurred while processing the request. instance: null ChunkingOptions: properties: size: oneOf: - type: integer minimum: 1 title: Positive integer description: A whole number greater than or equal to 1. examples: - 1 - type: 'null' description: >- The maximum number of tokens allowed in a chunk. If `null`, the maximum input length of the model will be used less overhead. examples: - 512 overlap_ratio: oneOf: - type: number exclusiveMaximum: 1 minimum: 0 title: Unit interval (closed, open) description: A number greater than or equal to 0 and less than 1. examples: - 0.5 - type: 'null' description: |- The proportion of the chunk size by which chunks should overlap. The ratio must be less than 1. If `null`, no overlapping will occur unless `overlap_tokens` is set. `overlap_ratio` and `overlap_tokens` cannot both be set. examples: - 0.1 - null overlap_tokens: oneOf: - type: integer minimum: 0 title: Non-negative integer description: A whole number greater than or equal to 0. examples: - 0 - type: 'null' description: |- The number of tokens by which chunks should overlap. If `null`, no overlapping will occur unless `overlap_ratio` is set. `overlap_tokens` and `overlap_ratio` cannot both be set. examples: - null - 10 type: object required: [] title: Chunking options description: Options for how to split text into smaller chunks. examples: - size: 512 overlap_ratio: 0.1 - size: 512 overlap_tokens: 10 - size: 512 AnswerExtraction: properties: index: type: integer minimum: 0 title: Non-negative integer description: >- The index of the text in the input array of texts that this result represents, starting from `0` (and, therefore, ending at the number of texts minus `1`). examples: - 0 answers: items: $ref: '#/components/schemas/Answer' type: array description: >- Answers extracted from the text, ordered from highest to lowest score. examples: - - text: >- 30 years if the person murdered was a police officer and 25 years in any other case start: 61 end: 144 score: 0.11460486645671249 inextractability_score: type: number maximum: 1 minimum: 0 title: Unit interval description: >- A score between `0` and `1`, inclusive, representing the likelihood that an answer can not be extracted from the text. Where this score is greater than the highest score of all possible answers, the text should be regarded as not having an extractable answer to the query. If that is the case and `ignore_inextractability` is `false`, no answers will be returned. examples: - 0.0027424068182309302 type: object required: - index - answers - inextractability_score title: Answer extraction description: The result of extracting answers from a text. examples: - index: 0 inextractability_score: 0.0027424068182309302 answers: - text: >- 30 years if the person murdered was a police officer and 25 years in any other case start: 61 end: 144 score: 0.11460486645671249 AnswerExtractionUsage: properties: input_tokens: type: integer minimum: 1 title: Positive integer description: The number of tokens inputted to the model. examples: - 43 type: object required: - input_tokens title: Answer extraction usage description: >- Statistics about the usage of resources in the process of extracting answers from the texts. examples: - input_tokens: 43 Answer: properties: text: type: string minLength: 1 description: The text of the answer. examples: - >- 30 years if the person murdered was a police officer and 25 years in any other case start: type: integer minimum: 0 title: Non-negative integer description: >- The index of the first character of the answer in the text, starting from `0` (and, therefore, ending at the number of characters in the text minus `1`). examples: - 61 end: type: integer minimum: 0 title: Non-negative integer description: >- The index of the character immediately after the last character of the answer in the text, starting from `0` (such that, in Python, the answer is equivalent to `text[start:end]`). examples: - 144 score: type: number maximum: 1 minimum: 0 title: Unit interval description: >- A score between `0` and `1`, inclusive, representing the strength of the answer. examples: - 0.11460486645671249 type: object required: - text - start - end - score title: Answer description: An answer extracted from a text. examples: - text: >- 30 years if the person murdered was a police officer and 25 years in any other case start: 61 end: 144 score: 0.11460486645671249 securitySchemes: APIKeyBearerTokenAuth: type: http description: >- An Isaacus-issued API key passed as a bearer token via the `Authorization` header in the format `Authorization: Bearer YOUR_API_KEY`. scheme: bearer bearerFormat: iuak_v1_APIKEYSECRET_CHECKSUM ````