Skip to main content
Retrieves the bounded text content for a source entity identified by a sourceCatalogUri. The URI is obtained from a Search Sources hit or from a source catalog. Use textKind to control the format of the returned text—plain text, markdown, page regions, or facet-scoped views. Large sources are paginated via cursor and nextCursor.

​
Endpoint

POST https://plangrep.com/api/open/v1/projects/{projectId}/source-text

​
Path Parameters

​
projectId
string
required
The unique identifier of the project that owns the source entity.

​
Request Body

Content-Type: application/json
​
sourceCatalogUri
string
required
Opaque URI identifying the source entity whose text you want to retrieve. Obtain this value from a sourceCatalogUri field on a search hit or from the source catalog. Must be at least 1 character.
​
reviewId
string
Optional review context identifier. When provided, scopes the text retrieval to sources associated with a specific review.
​
cursor
string
Pagination cursor. Pass the nextCursor value from a previous response to retrieve the next chunk of text. Omit to start from the beginning.
​
maxChars
integer
Maximum number of characters to return in a single response. Must be between 1 and 50,000. If the source text exceeds this limit, use nextCursor to retrieve the remainder.
​
facetId
string
Optional. Scopes the text retrieval to a specific facet within the source (e.g. a particular specification part). Must be a valid facetId belonging to the referenced source entity.
​
textKind
string
Controls the format and scope of returned text. One of:
ValueDescription
textPlain text extracted from the source (default).
markdownText formatted as Markdown, preserving structure where detected.
page_regionsText organized by detected page regions.
facet_source_textRaw source text scoped to the matched facet.
facet_match_textProcessed/normalized text for the matched facet, optimized for comparison.

​
Response

Returns a SourceTextResponse object.
​
status
string
Status of the text retrieval operation (e.g. success).
​
source
ProjectSource
Structured object describing the source entity.
​
sourceCatalogUri
string
The sourceCatalogUri from the request, echoed back.
​
text
string
The retrieved text content, up to maxChars characters (or the system default). Empty string if no text is available for the requested textKind.
​
cursor
string
The cursor value used for this response (echoed from the request).
​
nextCursor
string
Opaque cursor to pass as cursor in the next request to continue reading. null when there is no more text.
​
returnedChars
integer
Number of characters actually returned in text for this response.
​
textLength
integer
Total character length of the full source text (across all pages). Useful for progress indication.
​
hasMore
boolean
true if additional text is available beyond what was returned in this response.
​
textKind
string
The textKind that was applied, echoed back from the request (or the default if none was specified).
​
facet
object
If a facetId was specified, this contains the facet metadata associated with the returned text. null if no facet was specified or found.

​
Example Request

curl -X POST "https://plangrep.com/api/open/v1/projects/proj_abc123/source-text" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCatalogUri": "plangrep://projects/proj_abc123/specifications/spec_018/facets/facet_003",
    "textKind": "text",
    "maxChars": 5000
  }'

​
Example Response

{
  "status": "success",
  "source": {
    "type": "specification",
    "id": "spec_018",
    "label": "Section 07 13 26 – Self-Adhering Sheet Waterproofing"
  },
  "sourceCatalogUri": "plangrep://projects/proj_abc123/specifications/spec_018/facets/facet_003",
  "text": "PART 2 – PRODUCTS\n\n2.01 WATERPROOFING MEMBRANE\nA. Self-Adhering Sheet: ASTM D1970; SBS-modified bitumen; 40-mil minimum thickness...\n\n2.02 ACCESSORIES\nA. Primer: As recommended by membrane manufacturer...",
  "cursor": null,
  "nextCursor": "eyJvZmZzZXQiOjUwMDB9",
  "returnedChars": 5000,
  "textLength": 18340,
  "hasMore": true,
  "textKind": "text",
  "facet": {
    "facetId": "facet_003",
    "facetKey": "part_2_products",
    "facetKind": "part",
    "facetLabel": "PART 2 – PRODUCTS"
  }
}

​
Paginating Through Long Source Text

When hasMore is true, pass nextCursor back as cursor in a subsequent request to read the next chunk: 
curl -X POST "https://plangrep.com/api/open/v1/projects/proj_abc123/source-text" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCatalogUri": "plangrep://projects/proj_abc123/specifications/spec_018/facets/facet_003",
    "textKind": "text",
    "maxChars": 5000,
    "cursor": "eyJvZmZzZXQiOjUwMDB9"
  }'
Repeat until hasMore is false.

​
Error Responses

StatusDescription
400Invalid request body — sourceCatalogUri missing or empty, maxChars out of range.
401Missing or invalid Bearer token.
404Project or source entity not found.