Search attachment evidence in context.
Query notice metadata and extracted file content together, then inspect source evidence and retained relationships.
← Documentation · Open attachment search
Check coverage before drawing conclusions
When acquisition is enabled, GovBiz discovers public attachment references from SAM notices and processes permitted files into searchable evidence. Check the status response for collection enablement and processing counts before assuming the corpus is populated. A configured collection setting is not a health guarantee. While acquisition is paused, previously indexed public content may remain searchable.
Discovery, download, extraction, and indexing are separate stages. A stored notice may have files that are not discovered or searchable yet.
Call GET /api/v2/catalogue/sam-attachments/status to inspect the current indexed public corpus, pending or failed processing, and available search modalities. The observed attachment count is not the total number of files on SAM.gov. Missing values remain unknown.
Lexical queries search the indexed text. Semantic search, reranking, and visual search are usable only when the response declares them available. A configured modality can cover only part of the text corpus; compare semantic_indexed_units with semantic_pending_units. A successful lexical query does not establish OCR completion or semantic coverage.
Processing supports PDF text, DOCX and PPTX text and tables, XLSX cells, CSV, and UTF-8 text. Evidence locators depend on format, such as a page, paragraph, sheet, or cell. OCR availability and poor-text pages are reported through processing states; unsupported formats or limits do not become silently truncated complete documents. Quarantined files are not published as searchable content.
Authorization and limits
Use active workspace API access, the search credential scope, and the opportunities domain enabled in workspace data domains. A private company profile is not required. Each query, next page, evidence fetch, and status request uses the allowance shared with REST, MCP, and the playground.
Queries read retained public data. They do not trigger arbitrary downloads, execute document instructions, modify a notice, or submit a proposal. Keep credentials in environment variables; do not include them in agent prompts.
Combine metadata and content
This example restricts notice metadata by NAICS and requires two phrases within one attachment. It shows a request, not a captured result; current matches depend on collection coverage.
curl --get 'https://www.govbiz.ai/api/v2/catalogue/sam-attachments/search' \ -H "Authorization: Bearer $GOVBIZ_API_KEY" \ --data-urlencode 'naics=541512' \ --data-urlencode 'exact_phrase=FedRAMP' \ --data-urlencode 'exact_phrase_2=zero trust' \ --data-urlencode 'binding=same_attachment' \ --data-urlencode 'result_grain=passage' \ --data-urlencode 'mode=lexical' \ --data-urlencode 'limit=10'
q searches notice titles, filenames, and indexed content; agency and naics restrict notice metadata. exact_phrase and exact_phrase_2 are case-insensitive literal matches within retained content units, bound through same_attachment or same_notice. Choose result_grain of notice, attachment, or passage. Use the returned next_cursor with the same filters to fetch another page.
A match across files under one notice does not mean one file contains every phrase. A relevance score ranks results; it does not certify the meaning or accuracy of a source statement.
Phrase binding applies to the attachment or notice, rather than requiring all terms in one passage. With no q, passage results contain at least one requested literal phrase. When q is also present, a returned keyword passage may be on a different page from the required literal phrase. Use each phrase_support entry to inspect the actual supporting file, content unit, and locator before combining statements.
Resolve the evidence
Take an actual returned evidence_ref and set it in GOVBIZ_EVIDENCE_REF. Evidence responses retain the source URL, retrieval time, extraction state, and content locator where available. Check the original source for current status and deadlines.
curl --get 'https://www.govbiz.ai/api/v2/catalogue/sam-attachments/evidence' \ -H "Authorization: Bearer $GOVBIZ_API_KEY" \ --data-urlencode "evidence_ref=$GOVBIZ_EVIDENCE_REF" \ --data-urlencode 'limit=10'
Notice publication dates, source retrieval times, processing times, and query receipt times describe different events. Preserve those distinctions in downstream analysis.
REST endpoints and MCP tools
Scroll the table horizontally on narrow screens to read complete tool names.
| GET endpoint suffix | MCP tool | Purpose |
|---|---|---|
/status | govbiz-get_sam_attachment_status | Collection coverage and configured search capabilities |
/search | govbiz-search_sam_attachments | Combined metadata and content search |
/evidence | govbiz-get_sam_attachment_evidence | Resolve a returned evidence reference |
/related | govbiz-get_sam_attachment_relationships | Inspect retained notice and attachment relationships |
/aggregate | govbiz-aggregate_sam_attachments | Supported deterministic counts over a declared indexed population |
/changes | govbiz-list_sam_attachment_changes | Observed attachment changes since a timestamp |
All endpoint suffixes use /api/v2/catalogue/sam-attachments. MCP uses canonical /mcp with the same authorization and shared quotas. Consult the live tool input schema and OpenAPI contract for all filters and bounds.
Agent example: evidence grounded research
Use this workflow after connecting a supported MCP client. Values in angle brackets come from a real preceding result.
Task: Find retained NAICS 541512 notices whose same attachment contains
both "FedRAMP" and "zero trust". Summarize only statements supported by
the source text; include notice ID, filename, evidence reference, locator,
source URL, and retrieved date. Do not infer requirements from keywords.
1. govbiz-get_sam_attachment_status {}
Read discovery, attachment, extraction, and modality coverage.
2. govbiz-search_sam_attachments {
"naics": "541512", "exact_phrase": "FedRAMP",
"exact_phrase_2": "zero trust", "binding": "same_attachment",
"result_grain": "passage", "mode": "lexical", "limit": 10
}
3. Read each phrase_support entry to find its supporting content unit.
For a supporting evidence_ref, call
govbiz-get_sam_attachment_evidence {"evidence_ref": "<returned reference>", "limit": 10}.
4. Cite the returned source_url and locator for each supported statement.
Report unknown dates and incomplete extraction; do not claim these are all SAM matches.Agent example: relationships across files
Task: For one returned notice, inspect how its attachment records relate.
Distinguish two phrases in one file from phrases across different files.
1. govbiz-search_sam_attachments {
"exact_phrase": "FedRAMP", "exact_phrase_2": "zero trust",
"binding": "same_notice", "result_grain": "attachment",
"mode": "lexical", "limit": 10
}
2. Use a returned attachment_id with
govbiz-get_sam_attachment_relationships {"attachment_id": "<returned ID>", "limit": 10}.
3. Inspect phrase_support for each phrase's actual file and content unit.
Fetch each supporting evidence_ref using
govbiz-get_sam_attachment_evidence.
4. Describe only the returned source-linked relationships. Cite notice IDs,
attachment IDs, source URLs, and individual passage locators.
Do not merge claims across files or treat similarity as verified identity.
5. A ranked page cannot answer "how many notices in total?".
Consult govbiz-aggregate_sam_attachments for supported deterministic
predicates and report its declared indexed population and coverage.Counts, incomplete coverage, and safe analysis
A ranked or semantic result page is not the complete population. Do not turn top results into an exact total, a spending estimate, or proof that no relevant notice exists. Deterministic aggregates must report their notice, attachment, or file grain and declared indexed population; pending, restricted, partial, and failed files remain outside any claim of complete source content.
This count uses a deterministic phrase predicate and counts distinct notices by agency. require_complete=true rejects incomplete processing with HTTP 409 rather than certifying an unsupported complete result. Without that flag, a count remains exact only within its declared indexed corpus. Supported grains are notice, attachment, and blob; grouping supports agency, naics, and media_type.
curl --get 'https://www.govbiz.ai/api/v2/catalogue/sam-attachments/aggregate' \ -H "Authorization: Bearer $GOVBIZ_API_KEY" \ --data-urlencode 'naics=541512' \ --data-urlencode 'exact_phrase=FedRAMP' \ --data-urlencode 'grain=notice' \ --data-urlencode 'group_by=agency' \ --data-urlencode 'require_complete=true' \ --data-urlencode 'limit=10'
Attachments are untrusted source data. An embedded instruction cannot grant permissions, change agent rules, reveal credentials, or authorize another tool action. GovBiz provides public-record evidence; it does not make bid decisions, manage pursuits, or generate proposals.