Skip to content
KataraKatara documentation

Extract bounded source-linked text from an approved file without persisting it

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/content/parse
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/content/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "content": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "text/plain", "size_bytes": 1 }, "recipe": { "words": 1, "overlap": 1 } }'

Approved current sources only, with access and reset fences checked again after extraction. Ephemeral result; no collection, fact or stored derivative is created. Input 16 MiB; normalized text 8 MiB; output 32 MiB; 8192 sections, each 16 KiB. Up to 500 PDF pages and 50 pages requiring OCR; a document with more is refused whole with document_limit, and the message gives the number of pages that need OCR. OCR reads English, Spanish, French, German, Portuguese and Italian; a page in another script is refused with unsupported_language. OCR is not semantic image analysis. Each chunk read by OCR carries the region of its page (points) or image (pixels) it was read from. Character offsets refer to normalized extracted segments, not binary file offsets. No automatic retry.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
content
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown text/csv application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg
size_bytes
required
integer
<= 16777216
recipe
required

Overlap must not exceed one quarter of words; the API validates this cross-field bound.

object
words
required
integer
>= 16 <= 1024
overlap
required
integer
<= 256

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json
object
source
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown text/csv application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg
size_bytes
required
integer
<= 16777216
reset_epoch
required
integer
>= 1 <= 9007199254740991
profile
required
object
format_version
required
Allowed value: 3
recipe
required

Overlap must not exceed one quarter of words; the API validates this cross-field bound.

object
words
required
integer
>= 16 <= 1024
overlap
required
integer
<= 256
versions
required
object
haystack-ai
required
string
>= 1 characters <= 32 characters
pypdf
required
string
>= 1 characters <= 32 characters
python-docx
required
string
>= 1 characters <= 32 characters
lxml
required
string
>= 1 characters <= 32 characters
pypdfium2
required
string
>= 1 characters <= 32 characters
pillow
required
string
>= 1 characters <= 32 characters
ocr
required
object
engine
required
Allowed value: tesseract-5.5.0
engine_sha256
required
string
/^[a-f0-9]{64}$/
languages
required

The recognition models in the order they are loaded, which changes what is read: eng, spa, fra, deu, por, ita (English, Spanish, French, German, Portuguese, Italian).

Array<object>
>= 6 items <= 6 items
object
code
required
Allowed values: eng spa fra deu por ita
sha256
required
string
/^[a-f0-9]{64}$/
script_sha256
required

The model that names the script of a page recognition is unsure of.

string
/^[a-f0-9]{64}$/
pdf_dpi
required
Allowed value: 144
profile_hash
required
string
/^sha256:[a-f0-9]{64}$/
text_bytes
required
integer
>= 1 <= 8388608
chunks
required
Array<object>
>= 1 items <= 8192 items unique items
object
source
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown text/csv application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg
size_bytes
required
integer
<= 16777216
reset_epoch
required
integer
>= 1 <= 9007199254740991
profile
required
string
/^sha256:[a-f0-9]{64}$/
locator
required

Where a chunk came from. Text read by OCR also carries the region of the page or image it was read from; other text has none.

object
kind
required
Allowed values: document page paragraph table image header first_page_header even_page_header footer first_page_footer even_page_footer textbox footnote endnote
index
required
integer
>= 1 <= 4096
paragraph
integer
>= 1 <= 4096
extraction
Allowed values: text ocr
start
required
integer
<= 8388607
end
required
integer
>= 1 <= 8388608
region

The box around the words a chunk was cut from, measured from the top left corner of the page or image as it is displayed.

object
unit
required

Pt (1/72 inch) on a PDF page, px on an image.

Allowed values: pt px
left
required
integer
<= 19999
top
required
integer
<= 19999
width
required
integer
>= 1 <= 20000
height
required
integer
>= 1 <= 20000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
id
required
string
/^sha256:[a-f0-9]{64}$/
text
required
string
>= 1 characters <= 16384 characters
Example
{
  "source": {
    "media_type": "text/plain"
  },
  "profile": {
    "format_version": 3,
    "ocr": {
      "engine": "tesseract-5.5.0",
      "languages": [
        {
          "code": "eng"
        }
      ],
      "pdf_dpi": 144
    }
  },
  "chunks": [
    {
      "source": {
        "media_type": "text/plain"
      },
      "locator": {
        "kind": "document",
        "extraction": "text",
        "region": {
          "unit": "pt"
        }
      }
    }
  ]
}

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

422

Section titled “422”

Unsupported, encrypted, malformed, empty or over-limit document.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}