Extract field values from a document

post/extract

Extracts one field (question) or multiple fields (fields) from state or attached documents, returning the exact text from the document along with its character offsets (start, end). Values are copied directly from the source, never paraphrased or generated.

Body ParametersExpand Collapse

documents: optional array of object { b64, filename, mime, url }

Files whose text is added to the state as context (pdf, docx, pptx, xlsx, txt, md, csv, json, html, source code), each {b64 | url, filename?, mime?}. Per-file status comes back in document_notes.

b64: optional string

Base64-encoded file bytes.

filename: optional string

Helps format detection (e.g., memo.txt, contract.pdf).

mime: optional string

MIME type of the document.

url: optional string

Public HTTP(S) URL to fetch the document from.

fields: optional array of string

Several fields at once; the response maps each to its value.

question: optional string

One field to extract, e.g. "termination notice period".

state: optional string

The document text. Documents add to it.

ReturnsExpand Collapse

ExtractResult = object { field, found, grounded, 11 more }

Result of a single-field extraction (question).

field: string

The field that was asked for.

found: boolean

Whether the document contains a value for the field.

grounded: true

Always true: the value is copied from the document, not generated.

Accepts one of the following:

true

type: "extract"

The result type.

Accepts one of the following:

"extract"

value: string

The exact source text for the field; null when not found.

billable_tokens: optional number

Tokens billed for this request: max(1000, input_tokens).

confidence: optional number

Mean confidence over the selected text. Present when found.

minimum0

maximum1

document_notes: optional array of object { document, status, chars, 3 more }

Per-document status; present when documents were sent.

document: string

Filename or URL of the document, or (remaining) for documents that were never read because the context limit was already reached.

status: "included" or "skipped"

Accepts one of the following:

"included"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was skipped.

tokens: optional number

truncated: optional boolean

Present and true on an included document whose text was cut to fit the context limit (about 48,000 characters).

document_tokens: optional number

Document part of input_tokens; present when documents were sent.

end: optional number

Character offset where the value ends. Present when found.

image_tokens: optional number

Image-tile part of input_tokens.

input_tokens: optional number

Tokens processed for this request: text, attached documents and images.

start: optional number

Character offset where the value starts. Present when found.

truncated: optional boolean

Whether the input text was truncated before extraction.

ExtractFieldsResult = object { grounded, type, values, 5 more }

Result of a multi-field extraction (fields): each field name maps to its value.

grounded: true

Always true: values are copied from the document.

Accepts one of the following:

true

type: "extract"

The result type.

Accepts one of the following:

"extract"

values: map[object { field, found, grounded, 6 more } ]

One entry per requested field.

field: string

The field that was asked for.

found: boolean

Whether the document contains a value for the field.

grounded: true

Always true: the value is copied from the document, not generated.

Accepts one of the following:

true

type: "extract"

The result type.

Accepts one of the following:

"extract"

value: string

The exact source text for the field; null when not found.

confidence: optional number

Mean confidence over the selected text. Present when found.

minimum0

maximum1

end: optional number

Character offset where the value ends. Present when found.

start: optional number

Character offset where the value starts. Present when found.

truncated: optional boolean

Whether the input text was truncated before extraction.

billable_tokens: optional number

Tokens billed for this request: max(1000, input_tokens).

document_notes: optional array of object { document, status, chars, 3 more }

Per-document status; present when documents were sent.

document: string

Filename or URL of the document, or (remaining) for documents that were never read because the context limit was already reached.

status: "included" or "skipped"

Accepts one of the following:

"included"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was skipped.

tokens: optional number

truncated: optional boolean

Present and true on an included document whose text was cut to fit the context limit (about 48,000 characters).

document_tokens: optional number

Document part of input_tokens; present when documents were sent.

image_tokens: optional number

Image-tile part of input_tokens.

input_tokens: optional number

Tokens processed for this request: text, attached documents and images.

Extract field values from a document

curl https://api.articul8.ai/bivia/extract \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{}'

{
  "type": "extract",
  "field": "termination notice period",
  "value": "60 days",
  "start": 47,
  "end": 54,
  "confidence": 0.94,
  "found": true,
  "grounded": true,
  "input_tokens": 24,
  "image_tokens": 0,
  "billable_tokens": 1000
}

Returns Examples

{
  "type": "extract",
  "field": "termination notice period",
  "value": "60 days",
  "start": 47,
  "end": 54,
  "confidence": 0.94,
  "found": true,
  "grounded": true,
  "input_tokens": 24,
  "image_tokens": 0,
  "billable_tokens": 1000
}