---
name: pharmgkb-rest-requests
source: https://app.decimal.ai/s/pharmgkb-rest-requests@1/SKILL.md
source_sha256: 74e272c5e4d5
---

# PharmGKB Data REST API request grammar

## Contract
Enforce the PharmGKB (now branded ClinPGx) **Data REST API** request grammar: the fixed base URL, the
exact camelCase resource tokens, accession-by-path vs criteria-by-query lookups, the `view` detail
parameter, nested dot-notation filters, and the `{data, status}` response envelope. Apply whenever you
build, describe, or debug an HTTP call to PharmGKB.

## Rules
1. **Base URL** — every call targets `https://api.pharmgkb.org/v1/data`. The host is `api.pharmgkb.org`
   (never `www.pharmgkb.org`) and the path prefix is exactly `/v1/data` (a `v1` version segment, then
   `data`) — never `/api/v1`, never `/rest`, never `/v1` alone.
2. **Resource token** — the next path segment is exactly ONE resource type, always a **singular camelCase**
   token from this set:
   `gene`  `variant`  `chemical`  `haplotype`  `pathway`  `disease`
   `clinicalAnnotation`  `variantAnnotation`  `guidelineAnnotation`  `drugLabel`  `label`
   Never pluralize (`genes`), never snake_case (`clinical_annotation`), never capitalize the first letter
   (`Gene`).
3. **A drug is a `chemical`.** PharmGKB models any drug as the `chemical` resource — not `drug`, not
   `medication`.
4. **Dosing / prescribing guidelines are `guidelineAnnotation`** — NOT `dosingGuideline` (that resource
   does not exist; the API rejects it as an invalid type), not `guideline`, not `guidelines`.
5. **Two lookup shapes:**
   - **By accession** → put the accession as a PATH segment: `gene/PA124`. Returns a single object under
     `data`.
   - **By symbol / name / criteria** → use a QUERY string: `gene?symbol=CYP2C19`. Returns an array under
     `data`.
6. **Accession scheme** — every PharmGKB identifier is the letters `PA` followed by digits (e.g. `PA124`,
   `PA166154053`, `PA449726`). Never place a gene symbol, an rsID, or a bare number where an accession
   path segment belongs.
7. **Detail level** — the `view` query parameter selects verbosity; the allowed values are `min`, `base`,
   `max`. Use `view=max` for the full record and `view=min` for a compact one (`base` is the middle
   default). Do not invent `detail=`, `fields=`, `full=`, or `format=`.
8. **Filter by a related object** — use dot-notation on the nested field's `accessionId`, e.g.
   `clinicalAnnotation?relatedChemicals.accessionId=PA449726`. Only real object properties are accepted;
   do not invent flat params like `chemicalId=`, `drug=`, or `chemical=`.
9. **No pagination params** — the API has no `limit`, `page`, `per_page`, or `offset`. Unknown query keys
   are matched to object properties and rejected (`No such property: 'limit'`). Cap results client-side or
   request `view=min`.
10. **Response envelope** — parse a top-level object: `{"data": ..., "status": "success"}` on success;
    `{"status": "fail", "data": {"errors": [{"message": "..."}]}}` on failure. Every record carries an
    `objCls` type field (e.g. `"objCls":"Gene"`). It is never a bare top-level array.
11. **Rate limit** — at most 2 requests/second; exceeding it returns HTTP 429. Throttle client-side.

## Worked examples
- **Gene by symbol** —
  - wrong default: `GET https://www.pharmgkb.org/api/genes?name=CYP2C19`
  - conforming: `GET https://api.pharmgkb.org/v1/data/gene?symbol=CYP2C19`
- **Gene by accession, full detail** —
  - wrong: `GET https://api.pharmgkb.org/v1/data/gene?id=PA124&detail=full`
  - conforming: `GET https://api.pharmgkb.org/v1/data/gene/PA124?view=max`
- **Dosing guideline** —
  - wrong: `GET https://api.pharmgkb.org/v1/data/dosingGuideline?drug=clopidogrel`
  - conforming: `GET https://api.pharmgkb.org/v1/data/guidelineAnnotation?view=max`
- **Clinical annotations for a drug** —
  - wrong: `GET .../clinicalAnnotations?chemical=galantamine&limit=10`
  - conforming: `GET .../clinicalAnnotation?relatedChemicals.accessionId=PA449726&view=min`
- **Variant by rsID** —
  - wrong: `GET .../snp/rs4244285`
  - conforming: `GET .../variant?symbol=rs4244285`

## Edge cases & exceptions
- **rsIDs are not accessions.** Resolve a variant by rsID with `variant?symbol=rs4244285` (query), then use
  the returned `PA...` id for a direct `variant/PA166154053` fetch.
- **Drug known only by name.** Call `chemical?name=...` first to obtain its `PA` accession, then filter
  annotations by `relatedChemicals.accessionId=<that PA>`.
- **"Guideline" ambiguity.** Curated dosing/prescribing guidance is `guidelineAnnotation`; there is no
  `dosingGuideline` or `guideline` resource.
- **Capping results.** There is no server-side count param; slice the returned `data` array client-side or
  request `view=min`.
- **Empty vs error.** `status:"success"` with an empty `data` array means "no matches"; `status:"fail"`
  with `data.errors[].message` means a bad request (e.g. an unknown property).

## Do / Don't
- DO use host `api.pharmgkb.org` with `/v1/data`. DON'T use `www.pharmgkb.org`, `/api/v1`, or `/rest`.
- DO use singular camelCase resource tokens. DON'T pluralize or snake_case them.
- DO use `guidelineAnnotation` for dosing guidance. DON'T use `dosingGuideline`.
- DO use `chemical` for a drug. DON'T use `drug` or `medication`.
- DO fetch a known record by accession path segment (`gene/PA124`). DON'T pass it as `?id=`.
- DO select detail with `view=min|base|max`. DON'T invent `detail=`, `fields=`, or `format=`.
- DO filter with `relatedChemicals.accessionId=`. DON'T invent `chemicalId=` or `drug=`.
- DO throttle to <=2 req/s. DON'T append `limit`, `page`, or `offset`.

## Common mistakes
- Using `www.pharmgkb.org` or an `/api/v1` path instead of `api.pharmgkb.org/v1/data`.
- Pluralizing paths (`genes`, `variants`, `clinicalAnnotations`).
- `dosingGuideline` instead of `guidelineAnnotation`.
- `drug` / `drugs` instead of `chemical`.
- Passing an rsID or gene symbol where a `PA` accession path segment belongs.
- Adding `limit=` / `page=` (rejected as an unknown property).
- Expecting a bare JSON array instead of the `{data, status}` envelope.

## Quick checklist
- [ ] Base `https://api.pharmgkb.org/v1/data`
- [ ] Singular camelCase resource token
- [ ] `chemical` for drugs; `guidelineAnnotation` for dosing guidance
- [ ] Known record → accession path segment (`PA...`); search → `?symbol=` / `?name=`
- [ ] `view=min|base|max` for detail
- [ ] Related filter via `relatedChemicals.accessionId=`
- [ ] No `limit` / `page` / `offset`; <=2 req/s
- [ ] Parse `{data, status}` envelope + `objCls`