Skip to main content
Performs semantic and keyword search across all indexed sources within a project—including drawing regions, specification sections, and document entities. Returns ranked hits, each with a relevance score, a text snippet, a sourceCatalogUri you can pass to Read Source Text, and a structured source object describing the matched entity.
409 — Vector index not ready. If the project has searchable sources but the vector index has not finished building, the API returns 409 Conflict. Retry the request after a short wait (e.g. 5–10 seconds). This typically occurs immediately after a large batch of files finishes processing.

​
Endpoint

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

​
Path Parameters

​
projectId
string
required
The unique identifier of the project to search within.

​
Request Body

Content-Type: application/json
​
query
string
required
The search query string. Must be at least 1 character. Supports natural language and keyword queries (e.g. "waterproofing membrane below grade", "fire rating corridor").
​
reviewId
string
Optional review context identifier. When provided, scopes the search to sources associated with a specific review.
​
entityTypes
string[]
Optional list of entity type strings to restrict the search to specific source kinds (e.g. ["region", "specification", "doc"]).
​
maxHits
integer
Maximum number of search hits to return. Must be between 1 and 50. Defaults to a system value if omitted.
​
regionType
string
Filter hits to regions of this type (e.g. detail, plan, section).
​
layoutType
string
Filter hits to sources with this layout type.
​
drawingType
string
Filter hits to sources associated with this drawing discipline (e.g. architectural, structural).
​
sheetNumber
string
Filter hits to sources located on this sheet number.
​
fileName
string
Filter hits to sources from files whose name contains this substring (case-insensitive).
​
pageNumber
integer
Filter hits to sources on this specific 1-based page number.
​
classification
string
Filter hits to sources from files with this classification. One of: plans, specifications, documents, addenda, mixed, other.

​
Response

Returns a SourceSearchResponse object.
​
status
string
Status of the search operation (e.g. success).
​
query
string
The query string echoed back from the request.
​
hitCount
integer
Number of hits returned in this response.
​
searchedChunkCount
integer
Total number of indexed content chunks that were searched.
​
hits
object[]
Array of search hit objects, ordered by descending relevance score.

​
Example Request

curl -X POST "https://plangrep.com/api/open/v1/projects/proj_abc123/source-search" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "waterproofing membrane below grade",
    "maxHits": 5,
    "classification": "specifications"
  }'

​
Example Response

{
  "status": "success",
  "query": "waterproofing membrane below grade",
  "hitCount": 3,
  "searchedChunkCount": 4812,
  "hits": [
    {
      "score": 0.941,
      "snippet": "...self-adhering sheet waterproofing membrane applied to all below-grade foundation walls per ASTM D1970...",
      "sourceCatalogUri": "plangrep://projects/proj_abc123/specifications/spec_018/facets/facet_003",
      "source": {
        "type": "specification",
        "id": "spec_018",
        "label": "Section 07 13 26 – Self-Adhering Sheet Waterproofing"
      }
    },
    {
      "score": 0.887,
      "snippet": "...apply waterproofing membrane to exterior face of below-grade concrete walls. See Detail 4/A8.02...",
      "sourceCatalogUri": "plangrep://projects/proj_abc123/regions/region_204",
      "source": {
        "type": "region",
        "id": "region_204",
        "label": "DETAIL 4/A8.02"
      }
    }
  ]
}

​
Error Responses

StatusDescription
400Invalid request body — query missing or empty, maxHits out of range, etc.
401Missing or invalid Bearer token.
404Project not found.
409Searchable sources exist but the vector index is not ready yet. Retry after a short wait. Response body: { "error": { "code": "<string>", "message": "<string>" } }