Document intelligence · API concept

Evidence Extraction API

Turn supplied document text into structured answers with passage-level evidence for review.

APIConcept0.1.0-concept

Nothing in this preview is executable and no credentials are issued. This record is Concept — documentation preview only

When to use it

Check that it fits before you look at the detail.

Consider this when

Accept a supplied document representation and one or more questions.
Return answer objects designed to include page- or passage-level evidence.
Surface warnings and unanswered-question states.

Do not use it to

Validate that the underlying document is authentic, complete, or current.
Provide legal conclusions or professional advice.
Replace subject-matter review.

Who this is for

DevelopersTechnical evaluatorsImplementation partners

A caller needs structured answers that remain traceable to the supplied document representation.

Assumes: Ability to inspect structured outputs, evidence, limitations, and the stated human-review boundary.

Who decides what

What this concept may decide on its own, and what it may not.

A person decides

The caller validates the document and retains any legal, policy, compliance, or domain decision.

Citations support review; they do not replace qualified professional judgment.

It is not for

Legal conclusion
Authenticity validation
Automatic approval or action

What you get back

The shape of the exchange, and what happens when it is not sure.

You send

example_iddocumentquestionscitation_style

You receive

example_idstatusanswers

Shape taken from the synthetic supported answer example. It is not a stable contract.

Evidence

Each supported answer is designed to carry a source locator; unsupported questions return an unanswered state.

Uncertainty

The interface should abstain when the supplied text does not support an answer.

answer objectsevidence referenceswarningsunanswered-question statesreview flags

Next step

Continue with the evidence you need.

Inspect the reference

Conceptual inputs, outputs, and the contract fields that are still undefined.

Read the evidence

Four made-up cases — one answer it can support, and the three ways it declines to give one.

Conceptual contract

Reference

No base path, method, or schema is validated. The fields below describe intended information needs, not a stable contract.

Field	Type	Constraint
`document`	object	A synthetic or approved document representation; executable formats and size limits are not yet defined.
`questions`	array	At least one clearly worded question in the conceptual example.
`citation_style`	string	Conceptual values: passage or page; supported values are not yet validated.

Concept interface

Fields with no value yet are listed as not yet defined rather than omitted, so an undefined contract is distinguishable from an undocumented one.

Operation Name	Extract evidence-backed answers (conceptual)
Invocation Pattern	Single structured request and response (conceptual)
Base Path	Not yet defined
Method	Not yet defined
Media Type	application/json (conceptual)
Authentication	No public credentials issued

Outputs

answer objectsevidence referenceswarningsunanswered-question statesreview flags

Each supported answer is designed to carry a source locator; unsupported questions return an unanswered state.

Error and limit states

State	Meaning
`invalid_input`	Required input is missing or malformed.
`unsupported_request`	The request falls outside the documented capability or human decision boundary.
`unavailable_source`	A required source or supplied representation is unavailable.
`review_required`	Qualified review is required before interpretation, decision, commitment, or external use.
`service_unavailable`	Reserved for a later executable interface; not applicable to this documentation preview.

Data handling is not defined

Do not send production client data, confidential documents, credentials, or secrets through the public preview.

storage	Not yet defined
retention	Not yet defined
logging	Not yet defined
deletion	Not yet defined

Accepted data classes

Synthetic or intentionally generic data for public examples

Access

Availability	Documentation preview only
Eligibility	Developers, technical evaluators, institutional buyers, and implementation partners may discuss a bounded use case.
Onboarding	No credentials, SLA, pricing, or production integration are offered in V1.
Contact route	Email me

Synthetic evaluation set

Evidence

Each scenario is fictional or intentionally generic. Together they show a supported answer and the three ways this concept declines to give one — invalid input, abstention, and escalation to human review. No live request is sent.

Supported answer

Extract an approval threshold from a fictional procedure

Demonstrates the intended evidence link without implying a working endpoint or validated document.

Request

{
  "example_id": "evidence-extraction-api-happy-path",
  "document": {
    "document_id": "SYN-PROC-001",
    "title": "Example Equipment Purchase Procedure",
    "representation": "passages",
    "passages": [
      {
        "locator": "p. 2, para. 3",
        "text": "Purchases up to PHP 250,000 require approval from the department manager."
      },
      {
        "locator": "p. 2, para. 4",
        "text": "Purchases above PHP 250,000 require review by the procurement committee."
      }
    ]
  },
  "questions": [
    {
      "question_id": "Q1",
      "text": "What approval is required for a PHP 180,000 equipment purchase?"
    }
  ],
  "citation_style": "passage"
}

Response

{
  "example_id": "evidence-extraction-api-happy-path",
  "status": "supported",
  "answers": [
    {
      "question_id": "Q1",
      "answer": "The fictional procedure states that a PHP 180,000 purchase requires department-manager approval.",
      "evidence": [
        {
          "document_id": "SYN-PROC-001",
          "locator": "p. 2, para. 3"
        }
      ],
      "warnings": [
        "The underlying document has not been authenticated or checked for currency."
      ],
      "review_flags": [
        "underlying_document_not_validated"
      ]
    }
  ]
}

Invalid input

Reject a request with no document content

Shows conceptual validation feedback. Error codes are illustrative until an executable contract is reviewed.

Request

{
  "example_id": "evidence-extraction-api-invalid-input",
  "document": {
    "document_id": "SYN-EMPTY-001",
    "representation": "passages",
    "passages": []
  },
  "questions": [
    {
      "question_id": "Q1",
      "text": "What is the approval threshold?"
    }
  ]
}

Response

{
  "example_id": "evidence-extraction-api-invalid-input",
  "status": "invalid_input",
  "error": {
    "code": "DOCUMENT_CONTENT_REQUIRED",
    "message": "Provide at least one passage or supported document representation.",
    "field": "document.passages"
  }
}

Abstains

Abstain when the supplied text does not identify an approver

Makes the unanswered state visible when evidence is insufficient.

Request

{
  "example_id": "evidence-extraction-api-abstention",
  "document": {
    "document_id": "SYN-MEMO-001",
    "title": "Example Project Memo",
    "representation": "passages",
    "passages": [
      {
        "locator": "p. 1, para. 2",
        "text": "The project may begin on 15 September 2026."
      }
    ]
  },
  "questions": [
    {
      "question_id": "Q1",
      "text": "Who approved the project?"
    }
  ]
}

Response

{
  "example_id": "evidence-extraction-api-abstention",
  "status": "completed_with_abstention",
  "answers": [
    {
      "question_id": "Q1",
      "answer": null,
      "evidence": [],
      "unanswered_reason": "The supplied passage does not identify an approver.",
      "warnings": [
        "Do not infer an approver from the project start date."
      ]
    }
  ]
}

Human review

Route a compliance conclusion to professional review

Shows that evidence extraction does not replace legal, privacy, or compliance review.

Request

{
  "example_id": "evidence-extraction-api-human-review",
  "document": {
    "document_id": "SYN-POLICY-001",
    "title": "Example Data Handling Note",
    "representation": "passages",
    "passages": [
      {
        "locator": "p. 1, para. 1",
        "text": "Project files are stored in an approved internal workspace."
      }
    ]
  },
  "questions": [
    {
      "question_id": "Q1",
      "text": "Does this procedure satisfy all privacy obligations?"
    }
  ]
}

Response

{
  "example_id": "evidence-extraction-api-human-review",
  "status": "review_required",
  "answers": [
    {
      "question_id": "Q1",
      "answer": null,
      "evidence": [
        {
          "document_id": "SYN-POLICY-001",
          "locator": "p. 1, para. 1"
        }
      ],
      "review_reason": "The question asks for a legal or compliance conclusion that the extraction interface does not provide.",
      "review_flags": [
        "professional_review_required"
      ]
    }
  ]
}

What this record does not yet state

These facts have no value yet. They are listed rather than hidden, so the gap is visible before anyone relies on the record.

Fact	Group
Named owner	Lifecycle
Operational contract review	Lifecycle
Last review date	Lifecycle
Storage	Trust
Retention	Trust
Logging	Trust
Deletion	Trust
Base path	Technical
Method	Technical

Provenance

Source	Scope	Result
`SRC-REQ-001`	Purpose, input/output categories, proof requirement, examples, boundaries, and release posture.	Verified against supplied specification
`SRC-CAND-EVIDENCE-001`	Executable contract, source behaviour, supported limits, and operational evidence.	Defer

Source products

Product	Source	Verification
Evidence Extraction implementation contract or equivalent product behaviour	`SRC-CAND-EVIDENCE-001`	Not yet supplied

Version record

0.1.0-concept

Initial concept record derived from the approved content specification.

Last reviewed	Never reviewed
Content aligned	12 Aug 2026

Publication blockers

Operational contract not supplied
Owner and reviewer not assigned
Data-handling posture not defined
Canonical contact route not verified

Overview

Consider this when

Do not use it to

Who this is for

It is not for

Continue with the evidence you need.

Reference

Concept interface

Outputs

Error and limit states

Data handling is not defined

Accepted data classes

Access

Evidence

Extract an approval threshold from a fictional procedure

Request

Response

Reject a request with no document content

Request

Response

Abstain when the supplied text does not identify an approver

Request

Response

Route a compliance conclusion to professional review

Request

Response

What this record does not yet state

Provenance

Source products

0.1.0-concept

Publication blockers