{"openapi":"3.1.0","info":{"title":"Provider Directory Integrity API","description":"\nIndependent evidence on the accuracy of published provider directories.\n\nDirectories are read from the machine-readable index each issuer registers\nwith CMS, and every clinician listed in them is checked against federal\nregistries. Findings carry the date the fact became true, so a listing that\nwas correct when published is separable from one that was not.\n\nScope note: figures are per published directory index, and a single index can\nserve more than one issuer. Directory counts and issuer counts are therefore\nnot interchangeable, and neither is a plan count.\n","version":"1.0.0"},"servers":[{"url":"/services/directory"}],"paths":{"/v1/directory/index":{"get":{"tags":["Directory"],"summary":"National directory integrity index","operationId":"national_index_v1_directory_index_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response National Index V1 Directory Index Get"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/directory/index/history":{"get":{"tags":["Directory"],"summary":"The index series","description":"Published snapshots, newest first. Each row states whether it may be\ncompared with the one before it — same method version, same check set.\nA method change is a visible series break, never a silent restatement.","operationId":"index_history_v1_directory_index_history_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":520,"minimum":1,"default":52,"title":"Limit"}},{"name":"method_version","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Which method's series to serve. Versions are parallel series over the same published observations, never restatements of each other.","default":"1.0","title":"Method Version"},"description":"Which method's series to serve. Versions are parallel series over the same published observations, never restatements of each other."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Index History V1 Directory Index History Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/v1/directory/index/method":{"get":{"tags":["Directory"],"summary":"Methodology, machine-readable","operationId":"index_method_v1_directory_index_method_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Index Method V1 Directory Index Method Get"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v1/directory/directories":{"get":{"tags":["Directory"],"summary":"Ranked directories","operationId":"directories_v1_directory_directories_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"order","in":"query","required":false,"schema":{"type":"string","pattern":"^(records|payer_id)$","default":"records","title":"Order"}},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^carried$"},{"type":"null"}],"description":"`carried` also returns directories that could not be read this period and are showing their last measurement.","title":"Include"},"description":"`carried` also returns directories that could not be read this period and are showing their last measurement."},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-W\\d{2}$"},{"type":"null"}],"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer.","title":"Period"},"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer."},{"name":"issuer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"description":"HIOS issuer id. A plan's own identifier — the payer_id here is derived from the index URL and is ours, not theirs.","title":"Issuer Id"},"description":"HIOS issuer id. A plan's own identifier — the payer_id here is derived from the index URL and is ours, not theirs."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"description":"Two-letter state of a served issuer.","title":"State"},"description":"Two-letter state of a served issuer."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Directories V1 Directory Directories Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/directories/{payer_id}":{"get":{"tags":["Directory"],"summary":"One directory","description":"One directory's own figures: rate, band, rank, contribution, coverage.\n\nGranted, not merely keyed. These are the numbers the site stopped\npublishing per directory, so the account asking has to be the one\naccountable for the directory — the same server-side join the findings\nexport uses, against the same table.","operationId":"directory_v1_directory_directories__payer_id__get","parameters":[{"name":"payer_id","in":"path","required":true,"schema":{"type":"string","title":"Payer Id"}},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-W\\d{2}$"},{"type":"null"}],"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer.","title":"Period"},"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Directory V1 Directory Directories  Payer Id  Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/directories/{payer_id}/history":{"get":{"tags":["Directory"],"summary":"One directory's series","description":"How one directory has moved, week by week.\n\nGranted, like the snapshot it extends. This route once rode the open tier\non the reasoning that /directories already served the same figure for\nevery directory — true then, false since that list went lean. Left open it\nwould make the rest of this boundary theatre: it serves per_10k and band\nper week, so iterating payer_ids rebuilds the current ranking a row at a\ntime, which is the league table with extra steps.\n\n`as_of_period` is the tell a reader needs — where it is set, that week did\nnot measure the directory and the value is an earlier week's, carried.","operationId":"directory_history_v1_directory_directories__payer_id__history_get","parameters":[{"name":"payer_id","in":"path","required":true,"schema":{"type":"string","title":"Payer Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":260,"minimum":1,"default":26,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Directory History V1 Directory Directories  Payer Id  History Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/directories/{payer_id}/findings":{"get":{"tags":["Directory"],"summary":"NPI-level findings","operationId":"findings_v1_directory_directories__payer_id__findings_get","parameters":[{"name":"payer_id","in":"path","required":true,"schema":{"type":"string","title":"Payer Id"}},{"name":"fmt","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|csv)$","default":"json","title":"Fmt"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"default":500,"title":"Limit"}},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-W\\d{2}$"},{"type":"null"}],"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer.","title":"Period"},"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Findings V1 Directory Directories  Payer Id  Findings Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/me":{"get":{"tags":["Directory"],"summary":"This account and what it may read","description":"What this key can do, answered by the same joins that enforce it.\n\nA caller who hit 403 on findings had no way to discover what they were\nentitled to: the message named a grant and nothing in the API could list\none. Reading the grant table back is the only honest answer, because it is\nthe table the gate reads.","operationId":"me_v1_directory_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Me V1 Directory Me Get"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/directory/directories/{payer_id}/findings/{npi}/dispute":{"post":{"tags":["Directory"],"summary":"Dispute one finding","description":"Record that a plan contests a finding we published.\n\nFiling does NOT resolve the finding, change the score, or remove the row\nfrom next week's list. A dispute that cleared its own finding would let any\naccount erase its score by objecting, so the transitions out of OPEN belong\nto us. What the filing buys the plan is that its objection is on the record\nagainst the run it was published in.\n\nScoped by the same grant the findings themselves are: only the plan whose\nissuer we serve can dispute that directory's findings. A finding we never\nasserted in that run is a 404 — there is nothing to contest.","operationId":"dispute_finding_v1_directory_directories__payer_id__findings__npi__dispute_post","parameters":[{"name":"payer_id","in":"path","required":true,"schema":{"type":"string","title":"Payer Id"}},{"name":"npi","in":"path","required":true,"schema":{"type":"integer","maximum":9999999999,"minimum":1000000000,"title":"Npi"}},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-W\\d{2}$"},{"type":"null"}],"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer.","title":"Period"},"description":"ISO week, as 2026-W33. Defaults to the newest published period. The last published attempt is that week's answer."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Dispute Finding V1 Directory Directories  Payer Id  Findings  Npi  Dispute Post"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/directories/{payer_id}/disputes":{"get":{"tags":["Directory"],"summary":"Disputes filed","description":"What this account has contested for this directory.\n\nScoped to the caller's own filings by organisation, not merely to the\ndirectory: one plan's objections are not another's to read.","operationId":"disputes_v1_directory_directories__payer_id__disputes_get","parameters":[{"name":"payer_id","in":"path","required":true,"schema":{"type":"string","title":"Payer Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Disputes V1 Directory Directories  Payer Id  Disputes Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/runs":{"get":{"tags":["Directory"],"summary":"Run history and its validation checks","description":"What \"is this run good\" looks like as data rather than a log line.\n\nPublished runs only. A RUNNING load's funnel counts and a HELD run's\nmovement numbers are exactly what the gate exists to keep in.\n\nCarries the period and attempt, because the series is weekly and a caller\nholding only run ids cannot tell which of three runs was the week's\nanswer — nor join this to /index/history, which is keyed on the period.","operationId":"runs_v1_directory_runs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Runs V1 Directory Runs Get"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/structural/index":{"get":{"tags":["Directory structural integrity"],"summary":"The structural series, market-wide","description":"Two rates, side by side and never summed.\n\nAggregate only: no directory is named here. A customer sees their own\ngranted directories by name through /directories/{payer_id}, and the rest\nof the market as a distribution.","operationId":"structural_index_v1_directory_structural_index_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO week, e.g. 2026-W34. Defaults to the newest published run.","title":"Period"},"description":"ISO week, e.g. 2026-W34. Defaults to the newest published run."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Structural Index V1 Directory Structural Index Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/structural/directories/{payer_id}":{"get":{"tags":["Directory structural integrity"],"summary":"One directory's structural findings","operationId":"structural_directory_v1_directory_structural_directories__payer_id__get","parameters":[{"name":"payer_id","in":"path","required":true,"schema":{"type":"string","title":"Payer Id"}},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO week, e.g. 2026-W34. Defaults to the newest published run.","title":"Period"},"description":"ISO week, e.g. 2026-W34. Defaults to the newest published run."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"default":500,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Structural Directory V1 Directory Structural Directories  Payer Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/directory/structural/method":{"get":{"tags":["Directory structural integrity"],"summary":"What the structural checks measure","operationId":"structural_method_v1_directory_structural_method_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Structural Method V1 Directory Structural Method Get"}}}}}}},"/v1/directory/chat":{"post":{"tags":["chat"],"summary":"Ask what a plan publishes","description":"Guards before bytes: FastAPI reads and decodes a parameter body\nbefore dependencies resolve, which would let malformed or outsized\nbodies cost parsing without ever meeting the rate limit. Taking the raw\nrequest puts the token bucket first and caps what is read off the wire.","operationId":"chat_v1_directory_chat_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Chat V1 Directory Chat Post"}}}}},"security":[]}}},"components":{"schemas":{"DisputeRequest":{"properties":{"field":{"type":"string","pattern":"^(deactivation|exclusion)$","title":"Field","description":"Which check's finding is being disputed."},"reason":{"type":"string","pattern":"^(not_our_provider|already_corrected|registry_error|other)$","title":"Reason","description":"not_our_provider · already_corrected · registry_error · other"},"detail":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Detail"},"contact":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}],"title":"Contact"}},"type":"object","required":["field","reason"],"title":"DisputeRequest","description":"A plan's objection to one finding, in its own words."},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},"type":"object","required":["code","message"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"x-api-key":{"type":"apiKey","in":"header","name":"x-api-key"}}},"security":[{"x-api-key":[]}]}