Tutorial: Query FDA Rules with CTWise API

Difficulty: Beginner Time to Complete: 15 minutes Prerequisites: CTWise API key, basic REST API knowledge

---

Goal

Learn how to query FDA regulatory rules using the CTWise Regulatory Rules Service (RRS) API. By the end of this tutorial, you'll be able to:

1. Search for FDA rules by keyword
2. Filter rules by regulatory domain
3. Retrieve specific rule details
4. Handle pagination for large result sets

---

Prerequisites

Before you begin, ensure you have:

• A CTWise API key (get one at app.orchestraprime.ai)
• curl or a REST client like Postman
• Basic understanding of JSON and REST APIs

---

Step 1: Set Up Your Environment

First, export your API key as an environment variable:

export CTWISE_API_KEY="your-api-key-here"
export CTWISE_API_BASE="https://kj2xss9yg9.execute-api.us-east-1.amazonaws.com/dev0/v1"

Verify your setup by checking the API health:

curl -s "${CTWISE_API_BASE}/catalog/sources" \
  -H "x-api-key: ${CTWISE_API_KEY}" \
  -H "Content-Type: application/json" | jq .

Expected Output:

{
  "sources": [
    {"id": "fda", "name": "FDA", "description": "Food and Drug Administration regulations"},
    {"id": "ich", "name": "ICH", "description": "International Council for Harmonisation guidelines"},
    ...
  ]
}

---

Step 2: Search FDA Rules by Keyword

To search for FDA rules related to "clinical trials", use the /rules endpoint with the source and query parameters:

curl -s "${CTWISE_API_BASE}/rules?source=fda&query=clinical+trials&limit=5" \
  -H "x-api-key: ${CTWISE_API_KEY}" \
  -H "Content-Type: application/json" | jq .

Expected Output:

{
  "rules": [
    {
      "id": "fda-21cfr312",
      "title": "21 CFR Part 312 - Investigational New Drug Application",
      "source": "fda",
      "category": "clinical_trials",
      "effective_date": "2024-01-15",
      "summary": "Requirements for investigational new drug applications...",
      "url": "https://www.ecfr.gov/current/title-21/chapter-I/subchapter-D/part-312"
    },
    ...
  ],
  "total": 47,
  "page": 1,
  "limit": 5
}

---

Step 3: Filter by Regulatory Category

CTWise organizes FDA rules into categories. To find all rules in the adverse_events category:

curl -s "${CTWISE_API_BASE}/rules?source=fda&category=adverse_events&limit=10" \
  -H "x-api-key: ${CTWISE_API_KEY}" \
  -H "Content-Type: application/json" | jq .

Available FDA Categories:

Category	Description
clinical_trials	IND applications, trial conduct
adverse_events	Safety reporting, FAERS
labeling	Drug labeling requirements
manufacturing	GMP, facility requirements
submissions	NDA, BLA, 510(k) requirements

---

Step 4: Retrieve Full Rule Details

Once you have a rule ID, retrieve the complete rule details:

RULE_ID="fda-21cfr312"

curl -s "${CTWISE_API_BASE}/rules/${RULE_ID}" \
  -H "x-api-key: ${CTWISE_API_KEY}" \
  -H "Content-Type: application/json" | jq .

Expected Output:

{
  "id": "fda-21cfr312",
  "title": "21 CFR Part 312 - Investigational New Drug Application",
  "source": "fda",
  "category": "clinical_trials",
  "effective_date": "2024-01-15",
  "last_updated": "2024-06-01",
  "summary": "Requirements for investigational new drug applications...",
  "full_text": "...",
  "references": [
    {"id": "fda-21cfr11", "relationship": "referenced_by"},
    {"id": "ich-e6", "relationship": "harmonized_with"}
  ],
  "url": "https://www.ecfr.gov/current/title-21/chapter-I/subchapter-D/part-312",
  "citations": [
    "21 U.S.C. 321",
    "21 U.S.C. 331"
  ]
}

---

Step 5: Handle Pagination

For large result sets, use pagination parameters:

# Page 1
curl -s "${CTWISE_API_BASE}/rules?source=fda&limit=10&page=1" \
  -H "x-api-key: ${CTWISE_API_KEY}" | jq '.rules | length'

# Page 2
curl -s "${CTWISE_API_BASE}/rules?source=fda&limit=10&page=2" \
  -H "x-api-key: ${CTWISE_API_KEY}" | jq '.rules | length'

Pagination Response Fields:

{
  "rules": [...],
  "total": 234,
  "page": 2,
  "limit": 10,
  "has_next": true,
  "has_prev": true
}

---

Step 6: Semantic Search (Advanced)

CTWise supports semantic search for natural language queries using two methods:

POST Method (Recommended for complex queries)

curl -s -X POST "${CTWISE_API_BASE}/semantic-search" \
  -H "x-api-key: ${CTWISE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the requirements for reporting serious adverse events in phase 3 trials?",
    "sources": ["fda"],
    "limit": 5
  }' | jq .

GET Method (Alternative via query parameters)

curl -s "${CTWISE_API_BASE}/rules/search?q=serious+adverse+events+phase+3&sources=fda&limit=5" \
  -H "x-api-key: ${CTWISE_API_KEY}" | jq .

Both methods return rules semantically relevant to your question, not just keyword matches.

---

Complete Code Example (Python)

import os
import requests

# Configuration
API_KEY = os.environ.get("CTWISE_API_KEY")
API_BASE = "https://kj2xss9yg9.execute-api.us-east-1.amazonaws.com/dev0/v1"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

def search_fda_rules(query: str, category: str = None, limit: int = 10):
    """Search FDA rules by keyword and optional category."""
    params = {
        "source": "fda",
        "query": query,
        "limit": limit
    }
    if category:
        params["category"] = category

    response = requests.get(f"{API_BASE}/rules", headers=headers, params=params)
    response.raise_for_status()
    return response.json()

def get_rule_details(rule_id: str):
    """Get full details for a specific rule."""
    response = requests.get(f"{API_BASE}/rules/{rule_id}", headers=headers)
    response.raise_for_status()
    return response.json()

# Example usage
if __name__ == "__main__":
    # Search for clinical trial rules
    results = search_fda_rules("clinical trials", category="clinical_trials", limit=5)
    print(f"Found {results['total']} rules")

    for rule in results["rules"]:
        print(f"  - {rule['id']}: {rule['title']}")

    # Get details for first result
    if results["rules"]:
        details = get_rule_details(results["rules"][0]["id"])
        print(f"\nRule Details: {details['title']}")
        print(f"Effective Date: {details['effective_date']}")

---

Troubleshooting

Error	Cause	Solution
401 Unauthorized	Invalid or missing API key	Check your x-api-key header
429 Too Many Requests	Rate limit exceeded	Wait and retry, or upgrade tier
404 Not Found	Invalid rule ID	Verify the rule ID exists
Empty results	No matching rules	Try broader search terms

---

Next Steps

• ICH Integration Tutorial - Query ICH guidelines
• Rule Updates Monitoring - Set up alerts for rule changes
• API Reference - Complete endpoint documentation

---

Feedback

Found an issue with this tutorial? Submit feedback or contact support@orchestraprime.ai.