---
title: "Read a request in plain words and return an editable reading"
method: POST
path: "/v1/parse"
---

# Read a request in plain words and return an editable reading

`POST /v1/parse`

## Request

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

## Request body

- ParseRequest
  - `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
  - `q` 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'
  - `locale` string
  - `expected_source_hash` string, nullable

## Response `200`

The reading, its editable parts, status and hash

- object
  - `data` 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
            - `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
              - …
          - `operations` ChipOperation[]
            - `op` 'set' | 'remove', required
            - `chip_id` string, required
            - `value` union
              - …
    - `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
            - `condition` union
              - …
            - `count` CountComparison, required
              - …
      - `match_expression` MatchExpression: Explicit logical scope; leaves remain ordinary source-verifiable predicates.
        - `op` 'all' | 'any' | 'not', required
        - `clauses` union[], required
          - union
            - Predicate
              - …
            - unknown
      - `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
            - `condition` union
              - …
            - `count` CountComparison, required
              - …
        - `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
            - MemberExpression
              - …
            - MemberPredicate
              - …
          - `count` CountComparison, required
            - `op` 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'ne', required
            - `value` integer, 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
            - MemberExpression
              - …
            - MemberPredicate
              - …
          - `count` CountComparison, required
            - `op` 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'ne', required
            - `value` integer, 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)