Search, dashboards and summaries

A template can define a summary — the facts to extract from each finished document (a notary, a date, an amount, the parties). Summaries feed a per-template dashboard, and both the document text and its summary feed full-text search. Everything is filtered by access before results, counts or snippets are returned.

Search documents

GET /api/documents/search searches the documents the caller can read.

curl -G https://thedocdealer.com/api/documents/search \
  -H "Authorization: Bearer $DOCDEALER_API_KEY" \
  --data-urlencode "q=perez 12345678Z" \
  --data-urlencode "limit=20"

The response is { items, total, limit, offset }. Each item carries its summary state and, when q is set, search.snippets: arrays of { text, match } parts — never HTML, so render the matches yourself. Identifiers match with or without separators: 12.345.678-Z finds 12345678Z.

Summaries

An admin defines the summary schema on the template; it is frozen on each published version, so documents are always summarized with their own version's schema:

{
  "fields": {
    "notario": { "type": "text", "instructions": "Notario autorizante" },
    "fecha": { "type": "date" },
    "importe": { "type": "number" },
    "comparecientes": {
      "type": "list",
      "items": {
        "type": "object",
        "properties": { "nombre": { "type": "text" }, "dni": { "type": "text" } }
      }
    }
  }
}

Types: text, number, date, boolean, object and list. A top-level key cannot change type between versions — rename it instead.

Extraction runs after every completed review of the document (a generation run or content-validations). It reads the final text first and the form second, and never invents: missing values are null, empty lists [].

• GET /api/documents/{documentId}/summary → { state, status, data, stale, templateVersionId, extractedAt, error, schema }.
• POST /api/documents/{documentId}/summary-extractions retries it (edit access, documents:generate).
• A summary whose document changed afterwards is kept and marked stale until the next extraction.
• A failed extraction never fails generation or validation.

Dashboards

GET /api/templates/{templateId}/dashboard returns { config, page }: the configured columns and one row per readable document of the template, across all its versions. It takes the same parameters as search. Columns are top-level summary keys chosen by an admin for everyone; a key a document's version does not have renders empty, and objects and lists open a detail view.

Configuring the schema (PUT …/summary-schema), the columns (PUT …/dashboard-columns) and backfilling older documents (POST /api/templates/{templateId}/summary-extractions) is reserved to organization admins.

Over MCP

search_documents, get_template_dashboard, get_document_summary and request_document_summary mirror the endpoints above with the same rules; admins also have set_template_summary_schema, set_template_dashboard_columns and request_template_summaries.