Extract structured data

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

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.

CLI

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" }
  }'

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.

CLI

mka1 llm extract extract-with-schema \
  --schema-id schema_invoice_123 \
  --model auto \
  --prompt 'Extract the structured invoice fields.' \
  --file ./invoice.pdf

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: in the OpenAPI spec, this endpoint is defined as application/json (the file field is sent as a binary-encoded string).

CLI

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

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.