---
title: "Read an exact editor snapshot without saving or authorizing work"
method: POST
path: "/v1/understand"
---

# Read an exact editor snapshot without saving or authorizing work

`POST /v1/understand`

## Request

- Base URL: `https://api.specstream.ai`
- URL: `https://api.specstream.ai/v1/understand`
- Auth: API key in header `Authorization`

## Request body

- LiveUnderstandingRequest: The workspace's reading snapshot, exactly as the ask box sends it.
  - `document_id` string, required
  - `revision` integer, required
  - `generation` integer
  - `text` string, required
  - `kind` 'local_business' | 'creator' | 'organization' | 'storefront_product' | 'app_listing' | 'job_posting' | 'scholarly_work' | 'tender' | 'grant' | 'software_repository' | 'software_package' | 'dataset' | 'clinical_trial' | 'regulatory_document' | 'vulnerability' | 'book' | 'podcast' | 'web_page' | 'knowledge_entity' | 'person'
  - `context` ReadingContext: Workspace hints. They never widen the request. The quote holds the context of the run.
    - `locale` string
    - `target_type` string, nullable
    - `source_collection` string, nullable
    - `operation` 'find' | 'extend' | 'add-facts' | 'refresh', nullable
    - `retained` RetainedRequest: An explicit dependency on an authorized, immutable prior research request. The label is display text only. It never selects records or changes the target. The server loads the actual Spec; callers cannot provide a replacement base.
      - `parent_find_id` string, required
      - `operation` 'extend' | 'add-facts' | 'refresh', required
      - `label` string, nullable
      - `ast_hash` string, nullable
  - `phase` 'fast' | 'refined'
  - `expected_source_hash` string, nullable

## Response `200`

Versioned source receipt

- object
  - `data` LiveUnderstandingResult, required
    - `document_id` string, required
    - `revision` integer, required
    - `generation` integer, required
    - `phase` 'fast' | 'refined', required
    - `context` ReadingContext, required: Workspace hints. They never widen the request. The quote holds the context of the run.
      - `locale` string
      - `target_type` string, nullable
      - `source_collection` string, nullable
      - `operation` 'find' | 'extend' | 'add-facts' | 'refresh', nullable
      - `retained` RetainedRequest: An explicit dependency on an authorized, immutable prior research request. The label is display text only. It never selects records or changes the target. The server loads the actual Spec; callers cannot provide a replacement base.
        - `parent_find_id` string, required
        - `operation` 'extend' | 'add-facts' | 'refresh', required
        - `label` string, nullable
        - `ast_hash` string, nullable
    - `source_hash` string, required
    - `request_hash` string, required
    - `receipt` ReadingReceipt, required: Source receipt in the shape the workspace reader draws; `result` stays the authority.
      - `text` string, required
      - `source_hash` string, required
      - `spans` ReceiptSpan[], required
        - `span_id` string, required
        - `text` string, required
        - `utf16_start` integer, required
        - `utf16_end` integer, required
        - `start` integer, required
        - `end` integer, required
        - `role` 'target' | 'quantity' | 'geography' | 'condition' | 'output' | 'syntax' | 'unknown', required
        - `state` 'typed' | 'discovery' | 'syntax' | 'unresolved', required
        - `ast_refs` string[]
        - `reason` string, required
      - `normalizations` ReceiptNormalization[]
        - `span_id` string, nullable
        - `utf16_start` integer, required
        - `utf16_end` integer, required
        - `start` integer, required
        - `end` integer, required
        - `from` string, required
        - `to` string, required
        - `reason` string, required
      - `refinement` 'enabled' | 'disabled', required
      - `ast` object, nullable, required
    - `result` ParseResult, required
      - `retained` RetainedRequest: An explicit dependency on an authorized, immutable prior research request. The label is display text only. It never selects records or changes the target. The server loads the actual Spec; callers cannot provide a replacement base.
        - `parent_find_id` string, required
        - `operation` 'extend' | 'add-facts' | 'refresh', required
        - `label` string, nullable
        - `ast_hash` string, nullable
      - `grading` ReadingGrade: Advisory only. It cannot change the request or approve a run.
        - `kind` 'local_business' | 'creator' | 'organization' | 'storefront_product' | 'app_listing' | 'job_posting' | 'scholarly_work' | 'tender' | 'grant' | 'software_repository' | 'software_package' | 'dataset' | 'clinical_trial' | 'regulatory_document' | 'vulnerability' | 'book' | 'podcast' | 'web_page' | 'knowledge_entity' | 'person', required
        - `strength` 'strong' | 'good' | 'weak', required
        - `path` 'catalog' | 'web' | 'knowledge', nullable, required
        - `conditions` ConditionGrade[]
          - `part_id` string, required
          - `field_id` string, nullable, required
          - `check` 'instant' | 'page' | 'own_words', required
          - `single_source` string, nullable
        - `suggestions` ReadingSuggestion[]
          - `part_id` string, required
          - `words` string, required
          - `span_id` string, nullable
          - `nature` 'stated' | 'judgment' | 'absence' | 'cross_page_count', required
          - `rewordings` CheckableRewording[]
            - `text` string, required
            - `condition` Predicate, required
              - …
            - `operations` ChipOperation[]
              - …
      - `understanding` Understanding
        - `spec_version` 'request_understanding.v1'
        - `raw` string, required
        - `source_hash` string, required
        - `request_hash` string, required
        - `locale` string, required
        - `spans` SourceSpan[], required
          - `span_id` string, required
          - `start` integer, required
          - `end` integer, required
          - `start_utf16` integer, required
          - `end_utf16` integer, required
          - `text` string, required
          - `role` 'target' | 'quantity' | 'geography' | 'condition' | 'output' | 'syntax' | 'unknown', required
          - `state` 'typed' | 'discovery' | 'syntax' | 'unresolved', required
          - `ast_refs` string[]
          - `reason` string, required
        - `normalizations` Normalization[]
          - `start` integer, required
          - `end` integer, required
          - `original` string, required
          - `normalized` string, required
          - `kind` 'spelling' | 'slang' | 'typography' | 'translation' | 'paraphrase', required
          - `reason` string, required
          - `authority` 'registered_rule' | 'recorded_equivalence', required
          - `assessment_id` string, nullable
        - `refinement` 'not_needed' | 'fast_only' | 'accepted' | 'unavailable' | 'uncertain' | 'invalid' | 'saturated' | 'disabled'
        - `assessment_id` string, nullable
        - `assessment` EquivalenceRecord
          - `assessment_id` string, required
          - `provider` string, required
          - `model` string, required
          - `verdict` 'equivalent', required
          - `segments` AssessedSpan[], required
            - `start` integer, required
            - `end` integer, required
            - `role` 'subject' | 'quantity' | 'geography' | 'condition' | 'output' | 'syntax' | 'unresolved', required
            - `normalized` string, required
            - `kind` 'identity' | 'spelling' | 'slang' | 'typography' | 'translation' | 'paraphrase', required
            - `reason` string, required
          - `assessed_ast_hash` string, nullable, required
          - `segment_verdicts` string[], required
          - `reason` string, required
          - `meaning` 'recorded_model_judgment_not_source_fact'
        - `acquisition` AcquisitionIntent, required: Read-only projection; requirements are pointers, never substitute predicates.
          - `spec_version` 'acquisition_intent.v1'
          - `source_hash` string, required
          - `ast_hash` string, nullable
          - `target` string, nullable
          - `discovery_terms` string[]
          - `requirement_refs` string[]
          - `output_refs` string[]
          - `unresolved_span_ids` string[]
          - `can_execute` boolean
          - `blocked_reasons` string[]
      - `decision_id` string, nullable
      - `status` 'runnable' | 'needs_edit' | 'rejected' | 'capability_pending' | 'compiler_unavailable' | 'unquoted_plan', required
      - `ast` QueryAst, required
        - `target_requirement` TargetRequirement
          - `contract` 'target-source-assertion.v1'
          - `entity_kind` 'place' | 'creator' | 'organization' | 'storefront_product' | 'app_listing' | 'job_posting' | 'scholarly_work' | 'tender' | 'grant' | 'software_repository' | 'software_package' | 'dataset' | 'clinical_trial' | 'regulatory_document' | 'vulnerability' | 'book' | 'podcast' | 'web_page' | 'knowledge_entity' | 'person', required
          - `text` string, required
          - `reading_policy_sha256` string, required
          - `max_candidates` integer
          - `max_passages` integer
          - `max_context_chars` integer
          - `max_source_chars` integer
          - `timeout_ms` integer
          - `evidence_meaning` 'interpreted_published_assertion'
          - `prior_knowledge_authority` false
          - `modifies_typed_predicates` false
        - `semantic_binding` SemanticBinding
          - `spec_version` 'semantic_binding.v1'
          - `catalog_sha256` string, required
          - `target_id` string, required
          - `footprint_id` string, nullable
        - `spec_version` 'query_ast.v1'
        - `entity_type` 'local_business' | 'creator' | 'organization' | 'storefront_product' | 'app_listing' | 'job_posting' | 'scholarly_work' | 'tender' | 'grant' | 'software_repository' | 'software_package' | 'dataset' | 'clinical_trial' | 'regulatory_document' | 'vulnerability' | 'book' | 'podcast' | 'web_page' | 'knowledge_entity' | 'person', required
        - `limit` QueryLimit, required
          - `max` integer
          - `inferred` boolean
        - `discovery` Discovery, required
          - `geography_scope` 'worldwide.v1', nullable
          - `term` string, required
          - `platforms` string[]
          - `searches` string[]
          - `role_phrases` string[]
          - `seed_identifiers` object
        - `geo` Geo
          - `kind` 'country' | 'locality' | 'admin1', required
          - `query_label` string, required
          - `country_code` string, nullable
          - `admin1_code` string, nullable, required
          - `locality` string, nullable, required
          - `postal_code` string, nullable, required
          - `status` 'qualified' | 'ambiguous' | 'unqualified', required
          - `source` 'gazetteer' | 'catalog' | 'alias' | 'well_formed', required
          - `geoname_id` integer, nullable
          - `near` Near: A distance from a point: "within 65 miles of 1417 E Fedora Ave, Fresno".
            - `point` string, required
            - `latitude` number, required
            - `longitude` number, required
            - `radius_km` number, required
        - `where` Predicate[], required
          - `field_id` string, required
          - `op` 'count_matches' | 'contains' | 'not_contains' | 'has_any' | 'has_all' | 'has_none' | 'before' | 'after' | 'on_or_before' | 'on_or_after' | 'gt' | 'lt' | 'ne' | 'not_in' | 'gte' | 'lte' | 'eq' | 'exists' | 'class_in' | 'in', required
          - `value` union, required
            - boolean
            - integer
            - number
            - string
            - string[]
            - CountMatches
              - …
        - `match_expression` MatchExpression: Explicit logical scope; leaves remain ordinary source-verifiable predicates.
          - `op` 'all' | 'any' | 'not', required
          - `clauses` union[], required
            - union
              - …
        - `output_fields` OutputField[]
          - `field_id` string, required
          - `required` boolean
        - `worded_conditions` WordedCondition[]
          - `condition_id` string, required
          - `words` string, required
          - `statement` string, required
          - `search_words` string
        - `worded_outputs` WordedOutput[]
          - `detail_id` string, required
          - `words` string, required
          - `description` string, required
          - `value_type` 'text' | 'number' | 'date' | 'url' | 'email' | 'phone' | 'yes_no'
          - `required` boolean
        - `sort` SortKey[], required
          - `field_id` string, required
          - `direction` 'asc' | 'desc', required
        - `locale` string, required
        - `inferred` InferredClause[], required
          - `field_id` string, required
          - `reason` string, required
        - `unsupported` UnsupportedClause[], required
          - `field_id` string, required
          - `op` 'count_matches' | 'contains' | 'not_contains' | 'has_any' | 'has_all' | 'has_none' | 'before' | 'after' | 'on_or_before' | 'on_or_after' | 'gt' | 'lt' | 'ne' | 'not_in' | 'gte' | 'lte' | 'eq' | 'exists' | 'class_in' | 'in', required
          - `value` union, required
            - boolean
            - integer
            - number
            - string
            - string[]
            - CountMatches
              - …
          - `reason` string, required
      - `chips` Chip[], required
        - `chip_id` string, required
        - `category` 'type' | 'category' | 'place' | 'rows' | 'predicate' | 'output', required
        - `field_id` string, nullable
        - `label` string, required
        - `value` union
          - boolean
          - integer
          - number
          - string
          - string[]
          - CountMatches
            - `condition` union
              - …
            - `count` CountComparison, required
              - …
        - `status` 'resolved' | 'ambiguous' | 'unsupported' | 'unresolved', required
      - `unsupported` UnsupportedClause[], required
        - `field_id` string, required
        - `op` 'count_matches' | 'contains' | 'not_contains' | 'has_any' | 'has_all' | 'has_none' | 'before' | 'after' | 'on_or_before' | 'on_or_after' | 'gt' | 'lt' | 'ne' | 'not_in' | 'gte' | 'lte' | 'eq' | 'exists' | 'class_in' | 'in', required
        - `value` union, required
          - boolean
          - integer
          - number
          - string
          - string[]
          - CountMatches
            - `condition` union
              - …
            - `count` CountComparison, required
              - …
        - `reason` string, required
      - `compiler_version` string, required
      - `ast_hash` string, nullable, required
      - `canonical_sentence` string, nullable, required
      - `notice` string, nullable: One plain line to show before any quote, such as when the request asks SpecStream to make something rather than find what exists.
      - `read_back` string, nullable: The reading in plain words, to show people. canonical_sentence stays the machine form.

## Other responses

- `default`: Error envelope

---

[API](https://skmtc.dev/specstream/apis/specstream-api.md) · [All operations](https://skmtc.dev/specstream/apis/specstream-api/llms.txt) · [OpenAPI document](https://skmtc.dev/specstream/apis/specstream-api/revisions/5a9f51143a13?raw)