> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured data

> Define a reusable extraction schema in the MKA1 API and extract structured fields from files.

The standalone Extract API builds on [Responses](/docs/responses) with a dedicated document-to-JSON workflow and reusable schemas.

Use the Extract resource when you want the MKA1 API to turn an uploaded document or image into structured JSON.
You can define the schema inline for a one-off request, or save a reusable schema template first.

## Create a reusable schema

Save a schema template when you want to run the same extraction shape many times.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  import { SDK } from '@meetkai/mka1';
  import { readFileSync } from 'node:fs';

  const sdk = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

  const schema = await sdk.llm.extract.createSchema({
    xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
    extractionSchema: {
      name: 'Invoice extraction',
      description: 'Extract invoice header fields from PDF invoices',
      schema: {
        type: 'object',
        properties: {
          invoice_number: { type: 'string' },
          vendor_name: { type: 'string' },
          total_amount: { type: 'number' },
          date: { type: 'string', format: 'date' },
        },
        required: ['invoice_number', 'total_amount'],
      },
      metadata: {
        document_type: 'invoice',
      },
    },
  });

  console.log(schema.data.id); // e.g. "schema_invoice_123"
  ```

  ```python Python SDK theme={null}
  from meetkai_mka1 import SDK
  import json

  sdk = SDK(bearer_auth="Bearer <mka1-api-key>")

  schema = sdk.llm.extract.create_schema(
      name="Invoice extraction",
      description="Extract invoice header fields from PDF invoices",
      schema={
          "type": "object",
          "properties": {
              "invoice_number": {"type": "string"},
              "vendor_name": {"type": "string"},
              "total_amount": {"type": "number"},
              "date": {"type": "string", "format": "date"},
          },
          "required": ["invoice_number", "total_amount"],
      },
  )

  print(schema.data.id)  # e.g. "schema_invoice_123"
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;
  using MeetKai.MKA1.Types.Requests;
  using System.Text.Json;

  var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

  // The Extract API is available at sdk.Llm.Extract
  // Use sdk.Llm.Extract.CreateSchema(...) to save a reusable schema
  // Refer to the API reference for the full method signature and types
  ```

  ```bash CLI theme={null}
  mka1 llm extract create-schema \
    -H 'X-On-Behalf-Of: <end-user-id>' \
    --body '{
      "name": "Invoice extraction",
      "description": "Extract invoice header fields from PDF invoices",
      "schema": {
        "type": "object",
        "properties": {
          "invoice_number": { "type": "string" },
          "vendor_name": { "type": "string" },
          "total_amount": { "type": "number" },
          "date": { "type": "string", "format": "date" }
        },
        "required": ["invoice_number", "total_amount"]
      },
      "metadata": { "document_type": "invoice" }
    }'
  ```

  ```bash Bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/extract/schema \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "name": "Invoice extraction",
      "description": "Extract invoice header fields from PDF invoices",
      "schema": {
        "type": "object",
        "properties": {
          "invoice_number": {
            "type": "string"
          },
          "vendor_name": {
            "type": "string"
          },
          "total_amount": {
            "type": "number"
          },
          "date": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "invoice_number",
          "total_amount"
        ]
      },
      "metadata": {
        "document_type": "invoice"
      }
    }'
  ```
</CodeGroup>

This returns a schema ID such as `schema_invoice_123`.

## Extract with the saved schema

Use the saved schema ID to extract data from a file.
The OpenAPI spec supports `multipart/form-data` for this request.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const file = { fileName: 'invoice.pdf', content: readFileSync('./invoice.pdf') };

  const result = await sdk.llm.extract.extractWithSchema({
    schemaId: 'schema_invoice_123',
    xOnBehalfOf: '<end-user-id>',
    requestBody: {
      model: 'auto',
      prompt: 'Extract the structured invoice fields.',
      file,
    },
  });

  console.log(result.data);
  ```

  ```python Python SDK theme={null}
  result = sdk.llm.extract.extract_with_schema(
      schema_id="schema_invoice_123",
      model="auto",
      file={
          "file_name": "invoice.pdf",
          "content": open("./invoice.pdf", "rb"),
      },
  )

  print(result.data)
  ```

  ```csharp C# SDK theme={null}
  var fileContent = await System.IO.File.ReadAllBytesAsync("./invoice.pdf");

  var result = await sdk.Llm.Extract.ExtractWithSchemaAsync(
      "schema_invoice_123",
      new ExtractWithSchemaRequestBody()
      {
          Model = "auto",
          Prompt = "Extract the structured invoice fields.",
          File = new ExtractWithSchemaFile()
          {
              FileName = "invoice.pdf",
              Content = fileContent,
          },
      }
  );

  Console.WriteLine(result.ExtractionResponse?.Data);
  ```

  ```bash CLI theme={null}
  mka1 llm extract extract-with-schema \
    --schema-id schema_invoice_123 \
    --model auto \
    --prompt 'Extract the structured invoice fields.' \
    --file ./invoice.pdf
  ```

  ```bash Bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/extract/schema/schema_invoice_123 \
    --request POST \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --form 'model=auto' \
    --form 'prompt=Extract the structured invoice fields.' \
    --form 'file=@./invoice.pdf'
  ```
</CodeGroup>

A successful response returns a JSON object with:

* `success`
* `data` containing the extracted fields
* `metadata` about the extraction run

## Use an inline schema for one-off work

If you do not need to reuse the schema, call `POST /api/v1/llm/extract` instead.
Provide your JSON Schema inline along with the extraction request fields.

Note: this endpoint uses `multipart/form-data`. In `multipart/form-data`, `schema` (and `metadata`, if provided) are sent as string fields that can contain either a JSON object or a JSON string.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const file = { fileName: 'invoice.pdf', content: readFileSync('./invoice.pdf') };

  const result = await sdk.llm.extract.extract({
    xOnBehalfOf: '<end-user-id>',
    requestBody: {
      model: 'auto',
      prompt: 'Extract the invoice number and total.',
      schema: JSON.stringify({
        type: 'object',
        properties: {
          invoice_number: { type: 'string' },
          total_amount: { type: 'number' },
        },
        required: ['invoice_number', 'total_amount'],
      }),
      // metadata: JSON.stringify({ source: 'invoices' }),
      file,
    },
  });

  console.log(result.data);
  ```

  ```python Python SDK theme={null}
  result = sdk.llm.extract.extract(
      model="auto",
      schema=json.dumps(
          {
              "type": "object",
              "properties": {
                  "invoice_number": {"type": "string"},
                  "total_amount": {"type": "number"},
              },
              "required": ["invoice_number", "total_amount"],
          }
      ),
      # metadata=json.dumps({"source": "invoices"}),
      file={
          "file_name": "invoice.pdf",
          "content": open("./invoice.pdf", "rb"),
      },
  )

  print(result.data)
  ```

  ```csharp C# SDK theme={null}
  var fileContent = await System.IO.File.ReadAllBytesAsync("./invoice.pdf");

  var result = await sdk.Llm.Extract.ExtractAsync(new ExtractRequestBody()
  {
      Model = "auto",
      Prompt = "Extract the invoice number and total.",
      Schema = JsonSerializer.Serialize(new
      {
          type = "object",
          properties = new
          {
              invoice_number = new { type = "string" },
              total_amount = new { type = "number" },
          },
          required = new[] { "invoice_number", "total_amount" },
      }),
      // Metadata = JsonSerializer.Serialize(new { source = "invoices" }),
      File = new ExtractFile()
      {
          FileName = "invoice.pdf",
          Content = fileContent,
      },
  });

  Console.WriteLine(result.ExtractionResponse?.Data);
  ```

  ```bash CLI theme={null}
  mka1 llm extract extract \
    --model auto \
    --prompt 'Extract the invoice number and total.' \
    --schema '{
      "type": "object",
      "properties": {
        "invoice_number": { "type": "string" },
        "total_amount": { "type": "number" }
      },
      "required": ["invoice_number", "total_amount"]
    }' \
    --file ./invoice.pdf
  ```

  ```bash Bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/extract \
    --request POST \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --form 'model=auto' \
    --form 'prompt=Extract the invoice number and total.' \
    --form 'schema={"type":"object","properties":{"invoice_number":{"type":"string"},"total_amount":{"type":"number"}},"required":["invoice_number","total_amount"]}' \
    --form 'file=@./invoice.pdf'
  ```
</CodeGroup>

Use the reusable schema flow when you want a stable contract across many files.

## Manage saved schemas

The Extract resource also lets you:

* Get a saved schema by ID.
* Update a saved schema.
* Delete a saved schema.

Use those endpoints when your extraction contract changes over time and you need to keep the schema in sync.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.