# Cure Cancer With AI — Public API Instructions (for AI agents)

This document describes how to use the Cure Cancer With AI public REST API. It is written to be consumed by an AI agent or developer. Follow it exactly.

## Overview

- Base URL: `https://www.curecancerwithai.com`
- Data endpoints are read-only (`GET`); the MAMMAL prediction endpoints are `POST` with a JSON body. All return JSON.
- The API exposes a continuously-updated oncology dataset: research papers, news, blog posts, FDA approvals, and clinical trials, plus a cross-dataset keyword search. It also exposes IBM MAMMAL biomedical model predictions: protein–protein interaction, drug–target interaction (pKd), and ClinTox clinical-trial toxicity.
- The API is free. You must authenticate every request with a free API key.

## MCP server (recommended for agents)

If you are an MCP-capable agent, connect to the remote Model Context Protocol server instead of calling HTTP directly. It exposes every endpoint below as a tool (e.g. `search_oncology`, `list_clinical_trials`, `predict_ppi`).

- Endpoint (Streamable HTTP): `https://www.curecancerwithai.com/api/mcp`
- Auth: send `Authorization: Bearer ccw_live_YOUR_KEY` as a request header.

```json
{
  "mcpServers": {
    "cure-cancer-with-ai": {
      "url": "https://www.curecancerwithai.com/api/mcp",
      "headers": { "Authorization": "Bearer ccw_live_YOUR_KEY" }
    }
  }
}
```

## Getting an API key

A user must sign in at `https://www.curecancerwithai.com/api-keys` and click "Create key". The full key (format `ccw_live_...`) is shown exactly once at creation and cannot be retrieved later. Store it securely. Keys can be revoked at any time from the same page.

## Authentication

Send the API key on every request using either header:

- `Authorization: Bearer ccw_live_YOUR_KEY` (preferred)
- `x-api-key: ccw_live_YOUR_KEY`

Requests with a missing, invalid, or revoked key return HTTP `401`.

## Rate limits

- Free tier: 100 requests per hour, per key (rolling 1-hour window).
- Every response includes these headers:
  - `X-RateLimit-Limit` — the hourly limit (100).
  - `X-RateLimit-Remaining` — requests remaining in the current window.
  - `X-RateLimit-Reset` — ISO 8601 timestamp when the window resets.
- Exceeding the limit returns HTTP `429` with a `Retry-After` header (seconds) and body `{ "error": "Rate limit exceeded.", "resetAt": "<ISO timestamp>" }`.

Agent guidance: read `X-RateLimit-Remaining` and back off before it reaches 0. On `429`, wait until `Retry-After` seconds have elapsed before retrying.

## Common query parameters

List endpoints support pagination:

- `limit` — results per page, 1–100 (default 20).
- `offset` — number of results to skip (default 0).

Many list endpoints also support:

- `cancerType` — filter by cancer type, e.g. `lung`, `breast`, `prostate`, `colorectal`, `melanoma`, `leukemia`, `lymphoma`.
- `search` — case-insensitive keyword search across the resource's main text fields.
- `from` / `to` — ISO date bounds (e.g. `2024-01-01`) on the resource's primary date field.

## Response shape

List endpoints return a `data` array plus pagination metadata:

```json
{
  "data": [ { "...": "record" } ],
  "pagination": {
    "total": 1280,
    "limit": 20,
    "offset": 0,
    "page": 1,
    "totalPages": 64
  }
}
```

Single-record endpoints return `{ "data": { ...record } }`.

Errors use a consistent shape:

```json
{ "error": "Invalid or revoked API key." }
```

## Endpoints

### 1. Research papers — `GET /api/v1/research`

Peer-reviewed oncology research papers from PubMed.

Query parameters: `cancerType`, `treatmentType`, `search` (title + abstract), `from`/`to` (publication date), `limit`, `offset`.

Returned fields: `id`, `pubmedId`, `title`, `abstract`, `authors[]`, `journal`, `publicationDate`, `cancerTypes[]`, `treatmentTypes[]`, `keywords[]`, `fullTextUrl`, `summaryPlain`.

```bash
curl "https://www.curecancerwithai.com/api/v1/research?cancerType=lung&search=osimertinib&limit=10" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 2. Single research paper — `GET /api/v1/research/{idOrPubmedId}`

Fetch one paper by internal `id` or PubMed id.

```bash
curl "https://www.curecancerwithai.com/api/v1/research/38123456" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 3. News — `GET /api/v1/news`

Curated cancer news articles.

Query parameters: `cancerType`, `search` (title + summary + content), `from`/`to` (published date), `limit`, `offset`.

Returned fields: `id`, `title`, `summary`, `source`, `url`, `publishedAt`, `cancerTypes[]`, `tags[]`.

```bash
curl "https://www.curecancerwithai.com/api/v1/news?cancerType=breast&limit=5" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 4. Blog posts — `GET /api/v1/blog`

Editorial blog articles. The list returns excerpts; use the single-post endpoint for full content.

Query parameters: `category`, `cancerType` (tag), `search` (title + excerpt + content), `limit`, `offset`.

Returned fields: `id`, `title`, `excerpt`, `slug`, `primaryCategory`, `cancerTypeTags[]`, `imageUrl`, `publishedAt`.

```bash
curl "https://www.curecancerwithai.com/api/v1/blog?limit=10" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 5. Single blog post — `GET /api/v1/blog/{slug}`

Fetch one blog post by slug, including full `content`.

```bash
curl "https://www.curecancerwithai.com/api/v1/blog/immunotherapy-breakthroughs" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 6. FDA approvals — `GET /api/v1/fda-approvals`

FDA-approved oncology drugs.

Query parameters: `cancerType`, `search` (drug name + generic name + indication), `from`/`to` (approval date), `limit`, `offset`.

Returned fields: `id`, `applicationNumber`, `drugName`, `genericName`, `company`, `approvalDate`, `cancerTypes[]`, `indication`, `url`, `labelPdfUrl`.

```bash
curl "https://www.curecancerwithai.com/api/v1/fda-approvals?cancerType=lung&limit=5" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 7. Clinical trials — `GET /api/v1/clinical-trials`

Clinical trials ingested from public registries.

Query parameters: `condition`, `status` (e.g. `RECRUITING`), `search` (title + description), `limit`, `offset`.

Returned fields: `id`, `nctId`, `title`, `description`, `conditions[]`, `status`, `startDate`, `completionDate`, `interventionType`, `keywords[]`.

```bash
curl "https://www.curecancerwithai.com/api/v1/clinical-trials?status=RECRUITING&limit=10" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 8. Single clinical trial — `GET /api/v1/clinical-trials/{nctId}`

Fetch one trial by NCT id (or internal id), including `eligibilityCriteria` and `locations`.

```bash
curl "https://www.curecancerwithai.com/api/v1/clinical-trials/NCT01234567" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

### 9. MASS search — `GET /api/v1/search`

Search a single keyword across every dataset at once, grouped by type.

Query parameters:
- `q` — required. The keyword to search for.
- `types` — optional comma-separated list to narrow datasets: `research,news,blog,fdaApprovals,clinicalTrials`.
- `cancerType` — optional filter applied to every dataset.
- `limit` — max results per dataset, 1–100 (default 5).

Response shape (note: different from list endpoints):

```json
{
  "query": "osimertinib",
  "results": {
    "research":       { "total": 12, "items": [ ] },
    "news":           { "total": 3,  "items": [ ] },
    "blog":           { "total": 1,  "items": [ ] },
    "fdaApprovals":   { "total": 2,  "items": [ ] },
    "clinicalTrials": { "total": 5,  "items": [ ] }
  }
}
```

```bash
curl "https://www.curecancerwithai.com/api/v1/search?q=osimertinib&types=research,fdaApprovals" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY"
```

## MAMMAL prediction endpoints

These run the IBM MAMMAL biomedical foundation model. They are `POST` endpoints that take a JSON body (`Content-Type: application/json`) and return `{ "data": { ... } }`. The model is CPU-bound and serialized server-side, so a call may take up to ~60 seconds; use a client timeout of at least 60s. Missing/invalid body fields return HTTP `422` with `{ "error": "..." }`.

### 10. Protein–protein interaction — `POST /api/v1/mammal/ppi`

Predict the binding-affinity class for two proteins.

Body parameters (JSON):
- `protein_a` — required. Amino-acid sequence, single-letter codes (`A C D E F G H I K L M N P Q R S T V W Y`), no spaces or FASTA headers.
- `protein_b` — required. Amino-acid sequence, single-letter codes.

Response: `{ "data": { "prediction": "<SENTINEL_ID_0><1><EOS>", "label": "1" } }`. `label` is `"1"` (interacting) or `"0"` (non-interacting).

```bash
curl -X POST "https://www.curecancerwithai.com/api/v1/mammal/ppi" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protein_a":"MADQLTEEQIAEF...","protein_b":"MSSKLLLAGLDIE..."}'
```

### 11. Drug–target interaction (pKd) — `POST /api/v1/mammal/dti`

Predict drug–target binding affinity as `pKd` (−log₁₀ Kd); higher = stronger predicted binding.

Body parameters (JSON):
- `target_seq` — required. Target protein amino-acid sequence (single-letter codes).
- `drug_seq` — required. Drug structure in SMILES notation.
- `norm_y_mean` — optional number. Normalization mean override.
- `norm_y_std` — optional number. Normalization standard-deviation override.

Response: `{ "data": { "pKd": 5.4932751 } }`.

```bash
curl -X POST "https://www.curecancerwithai.com/api/v1/mammal/dti" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_seq":"NLMKRCTRGFRKLGKCTTLEEEKCKTLYPRGQCTCSDSKMNTHSCDCKSC","drug_seq":"CC(=O)NCCC1=CNc2c1cc(OC)cc2"}'
```

### 12. ClinTox clinical-trial toxicity — `POST /api/v1/mammal/clintox`

Predict clinical-trial toxicity for a compound.

Body parameters (JSON):
- `smiles` — required. Compound structure in SMILES notation.

Response: `{ "data": { "pred": 0, "score": 0.000019 } }`. `pred` is `1` (toxic / likely to fail trials) or `0` (not toxic); `score` is the raw positive-class score.

```bash
curl -X POST "https://www.curecancerwithai.com/api/v1/mammal/clintox" \
  -H "Authorization: Bearer ccw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"smiles":"CC(CCl)OC(C)CCl"}'
```

## Code samples

### JavaScript (fetch)

```js
const API_KEY = process.env.CCWAI_API_KEY // "ccw_live_..."

async function getResearch(cancerType, search) {
  const url = new URL("https://www.curecancerwithai.com/api/v1/research")
  if (cancerType) url.searchParams.set("cancerType", cancerType)
  if (search) url.searchParams.set("search", search)
  url.searchParams.set("limit", "10")

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  })
  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`)
  const { data, pagination } = await res.json()
  return { data, pagination }
}
```

### Python (requests)

```python
import os
import requests

API_KEY = os.environ["CCWAI_API_KEY"]  # "ccw_live_..."
BASE = "https://www.curecancerwithai.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def mass_search(q, types=None, cancer_type=None, limit=5):
    params = {"q": q, "limit": limit}
    if types:
        params["types"] = ",".join(types)
    if cancer_type:
        params["cancerType"] = cancer_type
    r = requests.get(f"{BASE}/api/v1/search", headers=HEADERS, params=params, timeout=30)
    r.raise_for_status()
    return r.json()["results"]

print(mass_search("osimertinib", types=["research", "fdaApprovals"]))
```

## Best practices for AI agents

1. Always send the API key header; never embed it in user-facing output or logs.
2. Use `search` / MASS search (`/api/v1/search`) for broad discovery, then fetch single records by id/slug/nctId for full detail.
3. Page through results with `limit`/`offset`; check `pagination.totalPages`.
4. Respect rate limits: monitor `X-RateLimit-Remaining`, and on HTTP 429 wait for `Retry-After` seconds.
5. Treat all data as informational, not medical advice. Cite source URLs (`url`, `fullTextUrl`, `labelPdfUrl`) when presenting results to users.