> ## Documentation Index
> Fetch the complete documentation index at: https://docs.civiccontracts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search contracts

> Search open federal, state, and local solicitations in plain English via the Civic AI API.

Search open solicitations the same way the app does — plain-English queries over federal (SAM.gov), state, and local sources, with hybrid semantic + keyword ranking.

```
GET https://api.civiccontracts.com/v1/contracts/search
```

## Query parameters

| Parameter          | Type    | Description                                                                                                      |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `q`                | string  | **Required.** Plain-English query, e.g. `HVAC maintenance for schools`                                           |
| `states`           | string  | Comma-separated two-letter states, e.g. `VA,MD,DC`                                                               |
| `naics`            | string  | Comma-separated full NAICS codes, e.g. `541512,541519`. Matched exactly, so a prefix like `5415` returns nothing |
| `setAsides`        | string  | Comma-separated set-aside codes, e.g. `SBA,WOSB`                                                                 |
| `types`            | string  | Comma-separated notice types, e.g. `Solicitation,Presolicitation`                                                |
| `postedWithinDays` | number  | Only notices posted in the last N days                                                                           |
| `dueWithinDays`    | number  | Only notices due in the next N days                                                                              |
| `includeExpired`   | boolean | Include past-deadline notices (default `false`)                                                                  |
| `includeGrants`    | boolean | Include grant notices (default `false`)                                                                          |
| `sort`             | string  | `relevance` (default), `deadlineAsc`, or `postedDesc`                                                            |
| `page`             | number  | 1-based page (default `1`)                                                                                       |
| `pageSize`         | number  | Results per page, max `50` (default `20`)                                                                        |

## Example

```bash theme={null}
curl -H "Authorization: Bearer civic_YOUR_API_KEY" \
  "https://api.civiccontracts.com/v1/contracts/search?q=cybersecurity%20services&states=VA,MD&pageSize=2"
```

```json theme={null}
{
  "success": true,
  "data": {
    "query": "cybersecurity services",
    "totalReturned": 17,
    "page": 1,
    "pageSize": 2,
    "tookMs": 842,
    "results": [
      {
        "noticeId": "f450a08d093f48a587bae8a3588909f4",
        "title": "Security Programs Operational Support",
        "agency": "…",
        "naicsCode": "541512",
        "state": "VA",
        "setAside": null,
        "postedDate": "2026-07-10",
        "responseDeadLine": "2026-08-01",
        "uiLink": "https://…",
        "dataSource": "sam.gov"
      }
    ]
  }
}
```

Use `noticeId` when [adding a pursuit to your pipeline](/api/pipeline#add-a-pursuit).