> ## Documentation Index > Fetch the complete documentation index at: https://docs.totoy.ai/llms.txt > Use this file to discover all available pages before exploring further. # Explains a document in any language > Explains a given document Source in any language in a specified output language and language level. ## OpenAPI ````yaml /api-reference/openapi.yaml post /explanation openapi: 3.0.3 info: title: Totoy API description: >- Explain documents in simple, plain or detailed language and create Knowledge Bases from your documents in 19 languages. termsOfService: https://www.totoy.ai contact: name: Totoy Support email: support@totoy.ai license: name: MIT url: https://raw.githubusercontent.com/totoy-ai/totoy-openapi/main/LICENSE version: 1.1.5 servers: - url: https://api.totoy.ai/v1 security: - ApiKeyAuth: [] tags: - name: Explanation description: >- Given a document in any language, an output language and one of three language levels, the assistant will return an `Explanation` for this document. - name: Knowledge Bases description: >- Create `Knowledge Bases` from document or text `Sources` and chat with an assistant about them in 19 languages. - name: Sources description: >- `Sources` are used to upload documents (.pdf, .jpg or .png) or plain texts that can be used with features like `Explanation` or `Knowledge Bases.` - name: Projects description: '`Projects` are used to group `Knowledge Bases` and `Explanations`.' - name: Organization description: Get information about your `Organization`. paths: /explanation: post: tags: - Explanation summary: Explains a document in any language description: >- Explains a given document Source in any language in a specified output language and language level. operationId: createExplanation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExplanationRequest' examples: explanation-request-example-1: $ref: '#/components/examples/explanation-request-example-1' explanation-request-example-2: $ref: '#/components/examples/explanation-request-example-2' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExplanationResponse' examples: explanation-response-example-1: $ref: '#/components/examples/explanation-response-example-1' explanation-response-example-2: $ref: '#/components/examples/explanation-response-example-2' 4XX: $ref: '#/components/responses/general4XXResponse' 5XX: $ref: '#/components/responses/general5XXResponse' components: schemas: ExplanationRequest: title: ExplanationRequest type: object additionalProperties: false properties: output_language: $ref: '#/components/schemas/OutputLanguage' language_level: $ref: '#/components/schemas/LanguageLevel' source_id: description: >- The unique identifier of the uploaded `Source` to be used as context for the `Explanation`. maxLength: 29 pattern: ^src_[a-zA-Z0-9]{25}$ type: string example: src_dmZ7imKLaPcQnv5ckvGlOEAA7 messages: description: >- The conversation history. For an initial `Explanation` just provide an empty array or no messages. For follow-up questions, provide the entire conversation history. type: array items: $ref: '#/components/schemas/Message' maxItems: 50 example: [] markdown_response: description: >- Whether the response should be returned as Markdown formatted text. If 'false', the response will be returned in plain text. type: boolean default: true example: true required: - source_id - output_language - language_level ExplanationResponse: title: ExplanationResponse type: object properties: project_id: description: >- The unique identifier of the `Project` this `Explanation` was assigned to. The `Explanation` will be assigned to the `project_id` of the `Source`. maxLength: 28 pattern: ^pj_[a-zA-Z0-9]{25}$ type: string example: pj_avX7imfLaPcQnv5ckvGlOEBA9 output_language: $ref: '#/components/schemas/OutputLanguage' language_level: $ref: '#/components/schemas/LanguageLevel' source_id: description: >- The unique identifier of the uploaded `Source` that was used as context for the `Explanation`. maxLength: 29 pattern: ^src_[a-zA-Z0-9]{25}$ type: string example: src_dmZ7imKLaPcQnv5ckvGlOEAA7 answer: $ref: '#/components/schemas/Message' markdown_response: description: Whether the response is a Markdown formatted text. type: boolean example: true required: - project_id - output_language - language_level - source_id - answer - markdown_response OutputLanguage: title: OutputLanguage description: > The ISO 639-1 code for the language in which the `Explanation` should be generated. Supported Languages: - ar: Arabic - bs: Bosnian - cs: Czech - de: German - es: Spanish - en: English - fa: Farsi - fr: French - hr: Croatian - hu: Hungarian - it: Italian - pl: Polish - ro: Romanian - sk: Slovak - sl: Slovenian - sr: Serbian - tl: Tagalog - tr: Turkish - uk: Ukrainian - zh: Mandarin type: string enum: - ar - bs - cs - de - es - en - fa - fr - hr - hu - it - pl - ro - sk - sl - sr - tl - tr - uk - zh example: en LanguageLevel: title: LanguageLevel description: > One of three language levels for the generated text: 1. Simple Language: Answers are short and simple, using easy words and a clear structure. 2. Plain Language: Answers are short and the assistant explains complicated terms. 3. Detailed Language: Answers are not simplified and the assistant answers in detail. type: string enum: - simple - plain - detailed example: plain Message: title: Message description: > Represents a message within an `Explanation` or a `Knowledge Base Chat`. For `Explanations` - An `assistant` message is either an initial `Explanation` for the document when no messages were provided in the request or an answer to a user message in the provided conversation history. type: object additionalProperties: false properties: role: description: The entity that produced the message. One of `user` or `assistant`. type: string enum: - user - assistant content: description: The content of the message. The maximum length is 16,000 characters. type: string maxLength: 16000 references: type: array items: $ref: '#/components/schemas/Reference' maxItems: 50 required: - role - content example: role: assistant content: >- Hi! The co-founders of Totoy are Benedikt Hielscher, Francis Rafal, Marcel Koller, Michael Perger and Simon Hoffmann.[R1] Problem: title: Problem description: A Response Body for HTTP Problem Details in RFC 9457 format. type: object additionalProperties: false properties: type: description: A URI reference that identifies the problem type. type: string maxLength: 512 example: https://docs.totoy.ai/probs/out-of-credit title: description: A short, human-readable summary of the problem type. type: string maxLength: 512 example: You do not have enough credit. status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. type: integer format: int32 example: 403 detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string maxLength: 4096 example: You do not have enough credit to perform this operation. instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string maxLength: 512 example: /projects/pj_avX7imfLaPcQnv5ckvGlOEBA9 Reference: title: Reference description: > Represents a reference to a `Source` that was used to generate the answer. The reference is used to provide backlinks to the original source and to provide context for the generated answer. type: object additionalProperties: false properties: text: description: String in the message content that needs to be replaced. type: string maxLength: 8 example: '[R1]' source_id: description: What `Source` the generated answer depended on. maxLength: 29 pattern: ^src_[a-zA-Z0-9]{25}$ type: string page_number: description: >- The page number in the `Source` the generated answer depended on. Only applicable for documents. type: integer format: int32 example: 5 nullable: true minimum: 1 maximum: 1000 backlink: description: The backlink of the `Source`, so it can be called from the client. type: string maxLength: 512 example: https://www.example.com/text.pdf custom_metadata: $ref: '#/components/schemas/CustomMetadata' required: - text - source_id example: text: '[R1]' source_id: src_oXiYDg8QOc9JsOk86idRXiywD page_number: 5 backlink: https://www.totoy.ai/totoy-company-overview.pdf custom_metadata: internal_tag: general_documents CustomMetadata: title: CustomMetadata description: >- Custom optional metadata for a `Source` provided by a client. Up to 10 key-value pairs. type: object additionalProperties: true maxProperties: 10 example: internal_tag: general_documents examples: explanation-request-example-1: summary: Explanation Request Example 1 description: >- An example for generating a plain language `Explanation` in English for a German source document. value: output_language: en language_level: plain source_id: src_dmZ7imKLaPcQnv5ckvGlOEAA7 markdown_response: true explanation-request-example-2: summary: Explanation Request Example 2 description: >- An example for a follow-up question based on the first answer from the first Explanation request. The entire conversation history has to be provided in the request and the new question has to be the last element in the messages array. value: output_language: en language_level: plain source_id: src_dmZ7imKLaPcQnv5ckvGlOEAA7 messages: - role: assistant content: >- Hey! This is a letter from the Austrian tax office. They are informing you about your obligation to submit quarterly VAT returns if your annual turnover is more than €35,000. However, if you submit a VAT return for the month of January on time, you can choose to submit monthly returns instead. If your annual turnover is more than €100,000, you are required to submit monthly VAT returns. Since your VAT returns and payments for 2021 do not cover the entire period, they are asking you to fill out the enclosed form to provide your actual annual turnover. This is important to avoid sending you incorrect reminders. If you have any questions, you can contact the service center at 050 233 233. Take care! - role: user content: Do I have to do something? markdown_response: true explanation-response-example-1: summary: Explanation Response Example 1 description: >- An example for a generated plain language `Explanation` in English for a German source document. value: project_id: pj_avX7imfLaPcQnv5ckvGlOEBA9 output_language: en language_level: plain source_id: src_dmZ7imKLaPcQnv5ckvGlOEAA7 answer: role: assistant content: >- Hey! This is a letter from the Austrian tax office. They are informing you about your obligation to submit quarterly VAT returns if your annual turnover is more than €35,000. However, if you submit a VAT return for the month of January on time, you can choose to submit monthly returns instead. If your annual turnover is more than €100,000, you are required to submit monthly VAT returns. Since your VAT returns and payments for 2021 do not cover the entire period, they are asking you to fill out the enclosed form to provide your actual annual turnover. This is important to avoid sending you incorrect reminders. If you have any questions, you can contact the service center at 050 233 233. Take care! markdown_response: true explanation-response-example-2: summary: Explanation Response Example 2 description: >- An example for a generated answer for a follow-up question to the second `Explanation` request. value: project_id: pj_avX7imfLaPcQnv5ckvGlOEBA9 output_language: en language_level: plain source_id: src_dmZ7imKLaPcQnv5ckvGlOEAA7 answer: role: assistant content: >- Yes, based on the information in the letter, you are required to fill out the enclosed form with your actual annual turnover and return it to your local tax office. This is necessary to ensure that your VAT returns and payments are accurate and to avoid receiving incorrect reminders. Please make sure to complete and return the form as requested. If you have any further questions or need assistance, you can contact the service center at 050 233 233. markdown_response: true responses: general4XXResponse: description: Client Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' general5XXResponse: description: Server Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKeyAuth: type: http scheme: bearer ````