Search

This workflow shows how to search across all clauses in your workspace using tag-based filtering, and how to retrieve the full text of a specific clause by ID.

Overview

1. Search for clauses  →  POST /clauses/search
2. Fetch a clause      →  GET  /clauses/{id}

All requests require x-api-key, x-workspace-id, and x-app-name headers. See Authentication.

---

Step 1 — Search for clauses

Search returns clauses across all documents in your workspace, filtered by tag. This is the primary way to find relevant provisions without knowing which document they live in.

API Reference: POST /clauses/search

POST /clauses/search
Content-Type: application/json

Request body:

{
  "filter": {
    "tagIds": ["tag_001", "tag_002"],
    "tagCategoryId": 5
  }
}

Field	Required	Description
filter.tagIds	Yes	One or more tag IDs to filter by
filter.tagCategoryId	No	Narrow results to a specific tag category

curl -X POST https://api.your-domain.com/clauses/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "x-app-name: my-app" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "tagIds": ["tag_001", "tag_002"]
    }
  }'

Response (200):

{
  "count": 8,
  "clauses": [
    {
      "clauseId": "98001",
      "documentId": "10567",
      "title": "Payment Terms",
      "text": "Payment shall be made within 30 days of the invoice date...",
      "depth": 2,
      "tagIds": ["tag_001"],
      "textBlockId": "70318",
      "similarity": 0.92,
      "endorsed": false,
      "date": "2024-03-01",
      "dateLastModified": "2024-04-10"
    }
  ]
}

Key fields:

Field	Description
clauseId	Unique clause identifier — use this to fetch the full clause
documentId	Which document this clause belongs to
title	Clause heading
text	Clause text as extracted
depth	Nesting depth (1 = top-level section)
similarity	Relevance score
tagIds	Tags applied to this clause

---

Step 2 — Fetch a clause by ID

Once you have a clauseId from search results, fetch the full clause object directly.

API Reference: GET /clauses/{id}

GET /clauses/{id}

curl https://api.your-domain.com/clauses/12345 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "x-app-name: my-app"

Replace 12345 with the numeric clauseId returned from Step 1.

Response (200):

{
  "clause": {
    "clauseId": "98001",
    "documentId": "10567",
    "title": "Payment Terms",
    "text": "Payment shall be made within 30 days of the invoice date...",
    "depth": 2,
    "tagIds": ["tag_001"],
    "textBlockId": "70318",
    "endorsed": false,
    "date": "2024-03-01",
    "dateLastModified": "2024-04-10",
    "comments": []
  }
}