Documentation

API reference

Query the same sources as the TaxMCP tools over HTTP: the Internal Revenue Code, Treasury Regulations, IRS publications and guidance, Tax Court opinions, and state tax law. Every result includes a citation URL back to the primary source.

Getting access

API access is included with the Team plan. Each team gets a pooled allowance of 5,000 requests per paid seat each month, shared by every key the team creates.

Create an API key

  1. Sign in at app.taxmcp.io and open your team.
  2. Choose API keys, name the key, and create it.
  3. Copy the key right away. It's shown once and can't be retrieved later.

Any team member can create keys. Members see and revoke their own keys; owners and admins can see and revoke every key on the team. A key stops working when its creator leaves the team.

Not on Team yet?

Team gives every member full Pro+ research coverage, plus team API keys, usage visibility, and centralized billing. Three-seat minimum.

Get started with Team

Authentication

Send your key in the Authorization header as a bearer token. The X-Api-Key header also works. Include Accept: application/json so errors always come back as JSON.

Base URL https://app.taxmcp.io/api/v1
Example request
curl "https://app.taxmcp.io/api/v1/search?query=qualified+business+income&limit=1" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"
Example response
{
  "results": [
    {
      "section_number": "199A",
      "title": "Qualified business income",
      "source_type": "irc",
      "jurisdiction": "federal",
      "content": "In the case of a taxpayer other than a corporation, except as provided in subsection (i), there shall be allowed as a deduction…",
      "relevance_score": 1.0,
      "source_url": "https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title26-section199A&num=0&edition=prelim",
      "effective_date": null,
      "last_amended_date": "2025-07-04",
      "last_amended_by": "Pub. L. 119-21",
      "superseded": null,
      "cross_references": ["1", "167", "168", "1385"]
    }
  ],
  "meta": {
    "total": 1,
    "query": "qualified business income"
  }
}

Keep keys server-side. Anyone with a key can spend your team's allowance, so revoke a key from the API keys page if it's exposed.

Endpoints

All endpoints are read-only GET requests that return JSON. Paths are relative to the base URL. Supported states are listed in the state coverage table.

GET /sections/{section} · Look up a section

Return the full text of an IRC section, Treasury Regulation, or state statute. Long sections come back as several chunks, ordered by chunk_index.

Parameters

  • section path · required · Section identifier, e.g. 199A, 1.199A-1, or GA-48-1-1 for state codes.
  • source_type string · optional · Disambiguate when an identifier exists in more than one source.
  • include_refs boolean · optional · Include cross_references on each chunk (default true).
curl "https://app.taxmcp.io/api/v1/sections/199A" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"

Returns results[] with section_number, heading, content, chunk_index, source_type, title, source_url, effective_date, last_amended_date, last_amended_by, and cross_references; meta.section and meta.total_chunks.

GET /publications/{number} · Get an IRS publication

Return the content of an IRS publication, optionally narrowed to one section. If the section isn't found, the 404 response lists available_sections.

Parameters

  • number path · required · Publication number, e.g. 946, 334, or 17.
  • section string · optional · A chapter (Ch2 or 2) or a heading keyword (MACRS, Section 179).
curl "https://app.taxmcp.io/api/v1/publications/946?section=MACRS" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"

Returns results[] in the same shape as section lookups; meta.publication and meta.total_chunks.

GET /rulings/{identifier} · Get a ruling or notice

Return a Revenue Ruling, Revenue Procedure, or Notice, flagging guidance the IRS has superseded, obsoleted, or revoked. Include the type in the identifier: a bare number like 2024-35 can match more than one document and returns 409 with the candidates in matches.

Parameters

  • identifier path · required · URL-encoded, e.g. Rev. Rul. 2024-01, Rev. Proc. 2024-35, or Notice 2024-35. Periods and case are optional.
curl "https://app.taxmcp.io/api/v1/rulings/Notice%202024-35" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"

Returns superseded (null, or treatment and superseded_by, e.g. Rev. Proc. 2025-30); results[] in the same shape as section lookups; meta.identifier and meta.total_chunks.

GET /cases/{query} · Get a Tax Court opinion

Return the full text of a U.S. Tax Court opinion. Appellate history isn't tracked, so confirm an opinion hasn't been reversed or vacated before relying on it.

Parameters

  • query path · required · URL-encoded reporter citation (142 T.C. 348) or case name (Soroban Capital Partners).
curl "https://app.taxmcp.io/api/v1/cases/142%20T.C.%20348" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"

Returns case with title, reporter_citation, court, decision_date, docket_number, precedential_status, and source_url; results[] with the opinion text; meta.query and meta.total_chunks.

GET /citing-cases/{query} · Get citing cases

Return a Tax Court opinion's citation history: later in-corpus opinions that cite it, and the opinions it cites. possible_negative_treatment is a heuristic from scanning citing opinions for negating language, not a Shepard's or KeyCite validity check.

Parameters

  • query path · required · URL-encoded reporter citation (1 T.C. 1) or case name (Eaton Paper Corp.).
curl "https://app.taxmcp.io/api/v1/citing-cases/1%20T.C.%201" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"

Returns case; cited_by[] and cites[] in the same shape as case; possible_negative_treatment[] with treatment and citing_case; meta.query, meta.cited_by_count, and meta.cites_count.

GET /references/{section} · Get cross-references

Return what a section cites (outbound) and what cites it (inbound), including Tax Court opinions that cite an IRC section.

Parameters

  • section path · required · Source section, e.g. 199A.
  • direction string · optional · inbound, outbound, or both (default).
curl "https://app.taxmcp.io/api/v1/references/199A?direction=inbound" \
  -H "Authorization: Bearer $TAXMCP_API_KEY" \
  -H "Accept: application/json"

Returns outbound[] with target_section, reference_text, and resolved; inbound[] with source_section, source_type, source_name, source_year, and reference_text; meta.outbound_count and meta.inbound_count.

GET /health returns {"status":"ok"} and doesn't require a key or count toward your allowance.

Errors

Errors use standard HTTP status codes. Most error bodies have an error field with a readable message; validation and per-minute rate limit errors use message instead.

  • 401 The API key is missing, invalid, or revoked.
  • 403 The key's team has no active Team plan, or the person who created the key is no longer a member.
  • 404 The section, publication, ruling, or case wasn't found. The response echoes the identifier you sent.
  • 409 A ruling identifier matches more than one document. Retry with one of the values in matches.
  • 422 A parameter failed validation. The response has a message and a per-field errors object.
  • 429 The key exceeded 60 requests per minute, or the team used its monthly allowance.

Rate limits & usage

Each key can make 60 requests per minute. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers, and a 429 includes Retry-After with the seconds to wait.

Your team's monthly allowance is 5,000 requests per paid seat, pooled across all keys, and resets at the start of each calendar month (UTC). Every request made with a valid key counts, including requests that return an error. Track usage on your team's API keys page.

Questions or need a higher limit? Email hello@taxmcp.io.