Semantic Search Endpoint

AI-powered semantic search across regulatory rules using natural language queries.

POST /v1/semantic-search

Search for regulatory rules using natural language. The API uses vector embeddings to find semantically similar content, returning the most relevant rules based on meaning rather than just keyword matching.

Request

POST https://api.ctwise.ai/v1/semantic-search
x-api-key: YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "query": "informed consent requirements for pediatric trials",
  "limit": 10,
  "sources": ["fda", "ich"],
  "threshold": 0.7
}

Parameters

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
limit	integer	No	Maximum results to return (default: 10, max: 50)
sources	string[]	No	Filter by data sources (default: all)
threshold	number	No	Minimum relevance score 0.0-1.0 (default: 0.5)

Available Sources

Source ID	Description
fda	FDA Guidance Documents
ich	ICH Guidelines (E6, E8, E9, etc.)
ema	European Medicines Agency
cdisc	CDISC Standards
who	WHO Guidelines
fda-oncology	FDA Oncology-Specific Guidance

Response

{
  "query": "informed consent requirements for pediatric trials",
  "total_results": 8,
  "results": [
    {
      "rule_id": "fda-rule-042",
      "title": "Informed Consent for Pediatric Subjects",
      "source": "fda",
      "source_document": "FDA Guidance: Pediatric Clinical Trials",
      "content": "When obtaining informed consent for pediatric subjects, investigators must ensure both parental permission and child assent are obtained...",
      "relevance_score": 0.92,
      "metadata": {
        "effective_date": "2023-06-15",
        "document_type": "Guidance",
        "therapeutic_area": "General"
      }
    },
    {
      "rule_id": "ich-e11-r1-003",
      "title": "ICH E11(R1) Pediatric Extrapolation",
      "source": "ich",
      "source_document": "ICH E11(R1) Addendum",
      "content": "The assent of pediatric subjects should be sought when the child is capable of understanding...",
      "relevance_score": 0.87,
      "metadata": {
        "effective_date": "2017-08-01",
        "document_type": "Guideline",
        "therapeutic_area": "General"
      }
    }
  ],
  "processing_time_ms": 842
}

Response Fields

Field	Type	Description
query	string	Original search query
total_results	integer	Number of results returned
results	array	Array of matching rules
results[].rule_id	string	Unique rule identifier
results[].title	string	Rule title
results[].source	string	Data source identifier
results[].source_document	string	Source document name
results[].content	string	Rule content/description
results[].relevance_score	number	Semantic similarity score (0.0-1.0)
results[].metadata	object	Additional metadata
processing_time_ms	integer	Processing time in milliseconds

Examples

Basic Search

curl -X POST "https://api.ctwise.ai/v1/semantic-search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "informed consent requirements",
    "limit": 5
  }'

Search with Source Filter

curl -X POST "https://api.ctwise.ai/v1/semantic-search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "adverse event reporting timelines",
    "sources": ["fda", "ich"],
    "limit": 10,
    "threshold": 0.7
  }'

Python Example

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.ctwise.ai/v1"

response = requests.post(
    f"{BASE_URL}/semantic-search",
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "query": "primary endpoint requirements for oncology trials",
        "sources": ["fda", "fda-oncology"],
        "limit": 10
    }
)

data = response.json()
print(f"Found {data['total_results']} results\n")

for result in data['results']:
    print(f"[{result['source']}] {result['title']}")
    print(f"  Relevance: {result['relevance_score']:.2f}")
    print(f"  Content: {result['content'][:100]}...")
    print()

JavaScript Example

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.ctwise.ai/v1';

const response = await fetch(`${BASE_URL}/semantic-search`, {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'data safety monitoring board requirements',
    limit: 10
  })
});

const data = await response.json();
console.log(`Found ${data.total_results} results`);

data.results.forEach(result => {
  console.log(`[${result.source}] ${result.title} (${result.relevance_score})`);
});

Error Responses

Missing Query Parameter

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'query' is required"
  }
}

Status: 400 Bad Request

Invalid API Key

{
  "message": "Unauthorized"
}

Status: 401 Unauthorized

Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 60
  }
}

Status: 429 Too Many Requests

Performance

Metric	Target
Response time	< 2 seconds
Max results	50 per request
Timeout	30 seconds

Tips for Better Results

1. Use natural language - Write queries as you would ask a question
2. Be specific - Include context like therapeutic area, phase, or document type
3. Adjust threshold - Lower threshold (0.5) for broader results, higher (0.8+) for precision
4. Filter by source - Use source filters to narrow down results

---

Related Endpoints

• GET /v1/rules - List and filter rules
• GET /v1/catalog/sources - Available data sources