Search API

Full-text search across frameworks, controls, evidence, policies, risks, findings, agents, and tickets.

Search

GET /api/v1/search

Search across all resource types or filter to a specific type.

Query Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	-	Search query text
type	string	No	-	Filter: frameworks, controls, evidence, policies, risks, findings, agents, tickets
limit	integer	No	20	Maximum results (1-100)
offset	integer	No	0	Pagination offset

Example Request

# Search across all types
curl "https://api.clawgrc.com/api/v1/search?q=access+control&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Search within a specific type
curl "https://api.clawgrc.com/api/v1/search?q=encryption&type=controls&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "results": [
    {
      "type": "control",
      "id": "uc-uuid",
      "title": "Encryption at Rest",
      "description": "All data must be encrypted at rest using AES-256 or equivalent...",
      "score": 0.95,
      "metadata": {
        "category": "Data Protection",
        "code": "DP-003"
      }
    },
    {
      "type": "policy",
      "id": "pol-uuid",
      "title": "Data Encryption Policy",
      "description": "This policy defines requirements for encryption of data...",
      "score": 0.82,
      "metadata": {
        "status": "approved",
        "version": 3
      }
    },
    {
      "type": "finding",
      "id": "finding-uuid",
      "title": "Unencrypted S3 bucket detected",
      "description": "S3 bucket 'logs-archive' does not have server-side encryption...",
      "score": 0.78,
      "metadata": {
        "severity": "high",
        "status": "open"
      }
    }
  ],
  "total": 15,
  "query": "encryption",
  "limit": 10,
  "offset": 0
}

Search Behavior

• Search uses PostgreSQL full-text search with GIN indexes for fast lookups
• Results are ranked by relevance score (0.0-1.0)
• Tenant-scoped resources (evidence, policies, risks, findings, agents, tickets) are filtered to the authenticated organization
• Global resources (frameworks, controls) are searchable by all organizations
• Search terms are tokenized and stemmed (e.g., "encrypting" matches "encryption")

Tips

• Use specific terms for better results: "MFA configuration" vs. "security"
• Search by control ID codes: "CC6.1" or "A.9.1.1"
• Combine terms: "AWS IAM access policy" narrows results effectively