{
  "openapi": "3.1.0",
  "info": {
    "title": "Cure Cancer With AI — Public API",
    "version": "1.0.0",
    "summary": "Free oncology data and IBM MAMMAL biomedical model predictions.",
    "description": "A free, public REST API over a continuously-updated oncology dataset — research papers (PubMed), curated news, blog posts, FDA-approved oncology drugs, and clinical trials — plus a cross-dataset keyword search and IBM MAMMAL biomedical foundation-model predictions (protein–protein interaction, drug–target affinity, and ClinTox clinical-trial toxicity).\n\nData endpoints are read-only `GET` requests; the MAMMAL prediction endpoints are `POST` requests with a JSON body. Every request must be authenticated with a free API key (format `ccw_live_...`), obtained at https://www.curecancerwithai.com/api-keys. Free tier: 100 requests/hour per key.\n\nHuman docs: https://www.curecancerwithai.com/developers — Agent instructions: https://www.curecancerwithai.com/ai-api-instructions.md",
    "contact": {
      "name": "Cure Cancer With AI",
      "url": "https://www.curecancerwithai.com/developers"
    },
    "license": {
      "name": "Free to use — see developer docs",
      "url": "https://www.curecancerwithai.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://www.curecancerwithai.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer documentation",
    "url": "https://www.curecancerwithai.com/developers"
  },
  "security": [
    { "bearerAuth": [] },
    { "apiKeyHeader": [] }
  ],
  "tags": [
    { "name": "Research", "description": "Peer-reviewed oncology research papers from PubMed." },
    { "name": "News", "description": "Curated cancer news articles." },
    { "name": "Blog", "description": "Editorial blog articles." },
    { "name": "FDA Approvals", "description": "FDA-approved oncology drugs." },
    { "name": "Clinical Trials", "description": "Clinical trials from public registries." },
    { "name": "Search", "description": "Cross-dataset keyword search." },
    { "name": "MAMMAL", "description": "IBM MAMMAL biomedical foundation-model predictions." }
  ],
  "paths": {
    "/api/v1/research": {
      "get": {
        "tags": ["Research"],
        "operationId": "listResearch",
        "summary": "List research papers",
        "description": "Peer-reviewed oncology research papers ingested from PubMed, including abstracts, authors, journal, and plain-language summaries.",
        "parameters": [
          { "$ref": "#/components/parameters/CancerType" },
          { "name": "treatmentType", "in": "query", "description": "Filter by treatment type.", "schema": { "type": "string" } },
          { "name": "search", "in": "query", "description": "Keyword search across title and abstract.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/From" },
          { "$ref": "#/components/parameters/To" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "A page of research papers.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/PaginatedResponse" },
                    { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchPaper" } } } }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/research/{idOrPubmedId}": {
      "get": {
        "tags": ["Research"],
        "operationId": "getResearchPaper",
        "summary": "Get a single research paper",
        "description": "Fetch one paper by its internal id or PubMed id.",
        "parameters": [
          { "name": "idOrPubmedId", "in": "path", "required": true, "description": "Internal id or PubMed id.", "schema": { "type": "string" }, "example": "38123456" }
        ],
        "responses": {
          "200": {
            "description": "The research paper.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResearchPaper" } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/news": {
      "get": {
        "tags": ["News"],
        "operationId": "listNews",
        "summary": "List news",
        "description": "Curated cancer news articles aggregated from trusted sources.",
        "parameters": [
          { "$ref": "#/components/parameters/CancerType" },
          { "name": "search", "in": "query", "description": "Keyword search across title, summary, and content.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/From" },
          { "$ref": "#/components/parameters/To" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "A page of news articles.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/PaginatedResponse" },
                    { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewsItem" } } } }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/blog": {
      "get": {
        "tags": ["Blog"],
        "operationId": "listBlog",
        "summary": "List blog posts",
        "description": "Editorial blog articles. Returns excerpts; fetch a single post by slug for full content.",
        "parameters": [
          { "name": "category", "in": "query", "description": "Filter by primary category.", "schema": { "type": "string" } },
          { "name": "cancerType", "in": "query", "description": "Filter by cancer-type tag.", "schema": { "type": "string" } },
          { "name": "search", "in": "query", "description": "Keyword search across title, excerpt, and content.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "A page of blog posts (excerpts).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/PaginatedResponse" },
                    { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPost" } } } }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/blog/{slug}": {
      "get": {
        "tags": ["Blog"],
        "operationId": "getBlogPost",
        "summary": "Get a single blog post",
        "description": "Fetch one blog post by slug, including the full article content.",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "description": "Blog post slug.", "schema": { "type": "string" }, "example": "immunotherapy-breakthroughs" }
        ],
        "responses": {
          "200": {
            "description": "The blog post including full content.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPost" } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/fda-approvals": {
      "get": {
        "tags": ["FDA Approvals"],
        "operationId": "listFdaApprovals",
        "summary": "List FDA approvals",
        "description": "FDA-approved oncology drugs with indication, company, approval date, and label links.",
        "parameters": [
          { "$ref": "#/components/parameters/CancerType" },
          { "name": "search", "in": "query", "description": "Keyword search across drug name, generic name, and indication.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/From" },
          { "$ref": "#/components/parameters/To" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "A page of FDA approvals.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/PaginatedResponse" },
                    { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FdaApproval" } } } }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/clinical-trials": {
      "get": {
        "tags": ["Clinical Trials"],
        "operationId": "listClinicalTrials",
        "summary": "List clinical trials",
        "description": "Clinical trials ingested from registries, including conditions, status, and intervention type.",
        "parameters": [
          { "name": "condition", "in": "query", "description": "Filter by condition.", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "description": "Filter by trial status, e.g. RECRUITING.", "schema": { "type": "string", "example": "RECRUITING" } },
          { "name": "search", "in": "query", "description": "Keyword search across title and description.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "A page of clinical trials.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/PaginatedResponse" },
                    { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClinicalTrial" } } } }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/clinical-trials/{nctId}": {
      "get": {
        "tags": ["Clinical Trials"],
        "operationId": "getClinicalTrial",
        "summary": "Get a single clinical trial",
        "description": "Fetch one trial by NCT id (or internal id), including eligibility criteria and locations.",
        "parameters": [
          { "name": "nctId", "in": "path", "required": true, "description": "NCT id or internal id.", "schema": { "type": "string" }, "example": "NCT01234567" }
        ],
        "responses": {
          "200": {
            "description": "The clinical trial with eligibility and locations.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClinicalTrial" } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "massSearch",
        "summary": "Cross-dataset keyword search",
        "description": "Search a keyword across every dataset at once — research, news, blog, FDA approvals, and clinical trials — with results grouped by type. Note: the response shape differs from the list endpoints.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "The keyword to search for.", "schema": { "type": "string" }, "example": "osimertinib" },
          { "name": "types", "in": "query", "description": "Optional comma-separated list to narrow datasets.", "schema": { "type": "string", "example": "research,fdaApprovals" } },
          { "name": "cancerType", "in": "query", "description": "Optional cancer-type filter applied to every dataset.", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "description": "Max results per dataset (1–100, default 5).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 } }
        ],
        "responses": {
          "200": {
            "description": "Search results grouped by dataset.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MassSearchResult" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/mammal/ppi": {
      "post": {
        "tags": ["MAMMAL"],
        "operationId": "predictPpi",
        "summary": "Protein–protein interaction",
        "description": "Predict the binding-affinity class for a pair of proteins using the IBM MAMMAL biomedical foundation model. The model is CPU-bound and serialized server-side; a call may take up to ~60s, so use a client timeout of at least 60 seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PpiRequest" },
              "example": { "protein_a": "MADQLTEEQIAEF...", "protein_b": "MSSKLLLAGLDIE..." }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PPI prediction.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PpiResult" } } }, "example": { "data": { "prediction": "<SENTINEL_ID_0><1><EOS>", "label": "1" } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/mammal/dti": {
      "post": {
        "tags": ["MAMMAL"],
        "operationId": "predictDti",
        "summary": "Drug–target interaction (pKd)",
        "description": "Predict drug–target binding affinity as pKd (−log₁₀ Kd). Higher pKd means stronger predicted binding. The model is CPU-bound; use a client timeout of at least 60 seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DtiRequest" },
              "example": { "target_seq": "NLMKRCTRGFRKLGKCTTLEEEKCKTLYPRGQCTCSDSKMNTHSCDCKSC", "drug_seq": "CC(=O)NCCC1=CNc2c1cc(OC)cc2" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DTI prediction.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DtiResult" } } }, "example": { "data": { "pKd": 5.4932751 } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/mammal/clintox": {
      "post": {
        "tags": ["MAMMAL"],
        "operationId": "predictClintox",
        "summary": "ClinTox clinical-trial toxicity",
        "description": "Predict clinical-trial toxicity for a compound. The model is CPU-bound; use a client timeout of at least 60 seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ClintoxRequest" },
              "example": { "smiles": "CC(CCl)OC(C)CCl" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ClinTox prediction.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClintoxResult" } } }, "example": { "data": { "pred": 0, "score": 0.000019 } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as a Bearer token: `Authorization: Bearer ccw_live_YOUR_KEY`. Get a free key at https://www.curecancerwithai.com/api-keys."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key in the `x-api-key` header (alternative to the Bearer token)."
      }
    },
    "parameters": {
      "Limit": { "name": "limit", "in": "query", "description": "Results per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
      "Offset": { "name": "offset", "in": "query", "description": "Number of results to skip (default 0).", "schema": { "type": "integer", "minimum": 0, "default": 0 } },
      "CancerType": { "name": "cancerType", "in": "query", "description": "Filter by cancer type, e.g. lung, breast, prostate, colorectal, melanoma, leukemia, lymphoma.", "schema": { "type": "string", "example": "lung" } },
      "From": { "name": "from", "in": "query", "description": "ISO date lower bound (e.g. 2024-01-01) on the resource's primary date field.", "schema": { "type": "string", "format": "date" } },
      "To": { "name": "to", "in": "query", "description": "ISO date upper bound on the resource's primary date field.", "schema": { "type": "string", "format": "date" } }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, invalid, or revoked API key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid or revoked API key." } } }
      },
      "NotFound": {
        "description": "The requested record was not found.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not found." } } }
      },
      "ValidationError": {
        "description": "Missing or invalid request body fields.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "protein_a is required." } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded (100 requests/hour per key). Includes a Retry-After header.",
        "headers": {
          "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "Rate limit exceeded.", "resetAt": "2026-06-11T12:00:00.000Z" } } }
      }
    },
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "example": 1280 },
          "limit": { "type": "integer", "example": 20 },
          "offset": { "type": "integer", "example": 0 },
          "page": { "type": "integer", "example": 1 },
          "totalPages": { "type": "integer", "example": 64 }
        }
      },
      "PaginatedResponse": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": {} },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        },
        "required": ["data", "pagination"]
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } },
        "required": ["error"]
      },
      "RateLimitError": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "Rate limit exceeded." },
          "resetAt": { "type": "string", "format": "date-time" }
        }
      },
      "ResearchPaper": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "pubmedId": { "type": "string" },
          "title": { "type": "string" },
          "abstract": { "type": "string" },
          "authors": { "type": "array", "items": { "type": "string" } },
          "journal": { "type": "string" },
          "publicationDate": { "type": "string", "format": "date" },
          "cancerTypes": { "type": "array", "items": { "type": "string" } },
          "treatmentTypes": { "type": "array", "items": { "type": "string" } },
          "keywords": { "type": "array", "items": { "type": "string" } },
          "fullTextUrl": { "type": "string", "format": "uri" },
          "summaryPlain": { "type": "string" }
        }
      },
      "NewsItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "source": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "publishedAt": { "type": "string", "format": "date-time" },
          "cancerTypes": { "type": "array", "items": { "type": "string" } },
          "tags": { "type": "array", "items": { "type": "string" } }
        }
      },
      "BlogPost": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "excerpt": { "type": "string" },
          "content": { "type": "string", "description": "Full article content (single-post endpoint only)." },
          "slug": { "type": "string" },
          "primaryCategory": { "type": "string" },
          "cancerTypeTags": { "type": "array", "items": { "type": "string" } },
          "imageUrl": { "type": "string", "format": "uri" },
          "publishedAt": { "type": "string", "format": "date-time" }
        }
      },
      "FdaApproval": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "applicationNumber": { "type": "string" },
          "drugName": { "type": "string" },
          "genericName": { "type": "string" },
          "company": { "type": "string" },
          "approvalDate": { "type": "string", "format": "date" },
          "cancerTypes": { "type": "array", "items": { "type": "string" } },
          "indication": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "labelPdfUrl": { "type": "string", "format": "uri" }
        }
      },
      "ClinicalTrial": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "nctId": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "conditions": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string", "example": "RECRUITING" },
          "startDate": { "type": "string", "format": "date" },
          "completionDate": { "type": "string", "format": "date" },
          "interventionType": { "type": "string" },
          "keywords": { "type": "array", "items": { "type": "string" } },
          "eligibilityCriteria": { "type": "string", "description": "Single-trial endpoint only." },
          "locations": { "type": "array", "items": { "type": "object" }, "description": "Single-trial endpoint only." }
        }
      },
      "MassSearchResultBucket": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "items": { "type": "array", "items": { "type": "object" } }
        }
      },
      "MassSearchResult": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "results": {
            "type": "object",
            "properties": {
              "research": { "$ref": "#/components/schemas/MassSearchResultBucket" },
              "news": { "$ref": "#/components/schemas/MassSearchResultBucket" },
              "blog": { "$ref": "#/components/schemas/MassSearchResultBucket" },
              "fdaApprovals": { "$ref": "#/components/schemas/MassSearchResultBucket" },
              "clinicalTrials": { "$ref": "#/components/schemas/MassSearchResultBucket" }
            }
          }
        }
      },
      "PpiRequest": {
        "type": "object",
        "required": ["protein_a", "protein_b"],
        "properties": {
          "protein_a": { "type": "string", "description": "Amino-acid sequence, single-letter codes (ACDEFGHIKLMNPQRSTVWY), no spaces or FASTA headers." },
          "protein_b": { "type": "string", "description": "Amino-acid sequence, single-letter codes." }
        }
      },
      "PpiResult": {
        "type": "object",
        "properties": {
          "prediction": { "type": "string", "example": "<SENTINEL_ID_0><1><EOS>" },
          "label": { "type": "string", "enum": ["0", "1"], "description": "1 = interacting, 0 = non-interacting." }
        }
      },
      "DtiRequest": {
        "type": "object",
        "required": ["target_seq", "drug_seq"],
        "properties": {
          "target_seq": { "type": "string", "description": "Target protein amino-acid sequence (single-letter codes)." },
          "drug_seq": { "type": "string", "description": "Drug structure in SMILES notation." },
          "norm_y_mean": { "type": "number", "description": "Optional. Normalization mean override." },
          "norm_y_std": { "type": "number", "description": "Optional. Normalization standard-deviation override." }
        }
      },
      "DtiResult": {
        "type": "object",
        "properties": {
          "pKd": { "type": "number", "description": "−log10 Kd. Higher = stronger predicted binding.", "example": 5.4932751 }
        }
      },
      "ClintoxRequest": {
        "type": "object",
        "required": ["smiles"],
        "properties": {
          "smiles": { "type": "string", "description": "Compound structure in SMILES notation." }
        }
      },
      "ClintoxResult": {
        "type": "object",
        "properties": {
          "pred": { "type": "integer", "enum": [0, 1], "description": "1 = toxic / likely to fail trials, 0 = not toxic." },
          "score": { "type": "number", "description": "Raw positive-class score.", "example": 0.000019 }
        }
      }
    }
  }
}