CDC configurations API
The configurations API from CDC — 15 operation(s) for configurations.
The configurations API from CDC — 15 operation(s) for configurations.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/cdc-configurations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: DIBBs eCR Refiner app-notifications Configurations API
description: 'Please visit the repo for more info: https://github.com/CDCgov/dibbs-ecr-refiner'
version: 1.0.0
servers:
- url: https://data.cdc.gov/resource
description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: configurations
paths:
/api/v1/configurations/:
get:
tags:
- configurations
summary: Get Configurations
description: "Returns a list of configurations based on the logged-in user.\n\nReturns:\n List of configuration objects."
operationId: getConfigurations
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/GetConfigurationsResponse'
type: array
title: Response Getconfigurations
post:
tags:
- configurations
summary: Create Configuration
description: Create a new configuration for a jurisdiction.
operationId: createConfiguration
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConfigInput'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConfigurationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}:
get:
tags:
- configurations
summary: Get Configuration
description: Get a single configuration by its ID including all associated conditions.
operationId: getConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigurationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/code-sets:
put:
tags:
- configurations
summary: Associate Condition Codeset With Configuration
description: "Associate a specified code set with the given configuration.\n\nArgs:\n configuration_id (UUID): ID of the configuration\n body (AssociateCodesetInput): payload containing a condition_id\n user (dict[str, Any], optional): User making the request\n db (AsyncDatabaseConnection, optional): Database connection\n\nRaises:\n HTTPException: 404 if configuration is not found in JD\n HTTPException: 404 if configuration is not found\n HTTPException: 409 if configuration is not a draft and therefore not editable\n HTTPException: 500 if configuration cannot be updated\n\nReturns:\n AssociateCodesetResponse: ID of updated configuration, the full list of included conditions,\n and the condition_name"
operationId: associateConditionWithConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateCodesetInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateCodesetResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/code-sets/{condition_id}:
delete:
tags:
- configurations
summary: Remove Condition Codeset From Configuration
description: "Remove a specified code set from the given configuration.\n\nArgs:\n configuration_id (UUID): ID of the configuration\n condition_id (UUID): ID of the condition to remove\n user (DbUser): User making the request\n db (AsyncDatabaseConnection): Database connection\n\nRaises:\n HTTPException: 404 if configuration is not found in JD\n HTTPException: 404 if condition is not found\n HTTPException: 409 if trying to remove the main condition\n HTTPException: 409 if configuration is not a draft and therefore not editable\n HTTPException: 500 if configuration is cannot be updated\n\nReturns:\n AssociateCodesetResponse: ID of updated configuration and the full list\n of included conditions plus condition_name"
operationId: disassociateConditionWithConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
- name: condition_id
in: path
required: true
schema:
type: string
format: uuid
title: Condition Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateCodesetResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/custom-codes:
post:
tags:
- configurations
summary: Add Custom Code
description: "Add a user-defined custom code to a configuration.\n\nArgs:\n configuration_id (UUID): The ID of the configuration to update.\n body (AddCustomCodeInput): The custom code information provided by the user.\n user (dict[str, Any]): The logged-in user.\n db (AsyncDatabaseConnection): The database connection.\n\nRaises:\n HTTPException: 404 if configuration isn't found\n HTTPException: 409 if configuration is not a draft and therefore not editable\n HTTPException: 500 if custom code can't be added\n\nReturns:\n ConfigurationCustomCodeResponse: Updated configuration"
operationId: addCustomCodeToConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddCustomCodeInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationCustomCodeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- configurations
summary: Edit Custom Code
description: "Modify a configuration's custom code based on system_key/code pair.\n\nArgs:\n configuration_id (UUID): The ID of the configuration to modify.\n body (UpdateCustomCodeInput): User-provided object containing custom code info.\n user (dict[str, Any]): The logged-in user.\n db (AsyncDatabaseConnection): The database connection.\n logger (Logger): The system logger.\n\nRaises:\n HTTPException: 409 if configuration is not a draft and therefore not editable\n HTTPException: 500 if the configuration can't be updated\n\nReturns:\n ConfigurationCustomCodeResponse: The updated configuration."
operationId: editCustomCodeFromConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomCodeInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationCustomCodeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/custom-codes/upload:
post:
tags:
- configurations
summary: Upload Custom Codes Csv
description: "Accepts a CSV payload in JSON body.\n\nExpected CSV headers:\n code_number,code_system,display_name\n\nReturns:\n UploadCustomCodesResponse"
operationId: uploadCustomCodesCsv
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadCustomCodesCsvInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UploadCustomCodesPreviewResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/custom-codes/confirm:
post:
tags:
- configurations
summary: Confirm Upload Custom Codes Csv
description: Confirm and save custom codes from preview list.
operationId: confirmUploadCustomCodesCsv
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmUploadCustomCodesInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UploadCustomCodesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/custom-codes/{system_key}/{code}:
delete:
tags:
- configurations
summary: Delete Custom Code
description: "Delete a custom code from a configuration.\n\nArgs:\n configuration_id (UUID): The ID of the configuration to modify.\n system_key (str): System of the custom code.\n code (str): Code of the custom code.\n user (dict[str, Any]): The logged-in user.\n db (AsyncDatabaseConnection): The database connection.\n\nRaises:\n HTTPException: 400 if system_key is not provided\n HTTPException: 400 if code is not provided\n HTTPException: 404 if configuration can't be found\n HTTPException: 409 if configuration is not a draft and therefore not editable\n HTTPException: 500 if configuration can't be updated\n\nReturns:\n ConfigurationCustomCodeResponse: The updated configuration"
operationId: deleteCustomCodeFromConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
- name: system_key
in: path
required: true
schema:
type: string
title: System Key
- name: code
in: path
required: true
schema:
type: string
title: Code
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationCustomCodeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/custom-codes/validate:
post:
tags:
- configurations
summary: Validate Custom Code
description: "Determines whether a custom code update is valid or not.\n\nIf the desired code is already associated with the configuration, then the update is\ninvalid.\n\nArgs:\n configuration_id (UUID): The configuration ID\n body (ValidateCustomCodeInput): Body including the code to validate\n user (DbUser, optional): The logged in user\n db (AsyncDatabaseConnection, optional): The database connection\n\nReturns:\n bool: Returns True if the code name has not been used, otherwise returns False"
operationId: validateCustomCodeFromConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateCustomCodeInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateCustomCodeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/export:
get:
tags:
- configurations
summary: Get Configuration Export
description: Create a CSV export of a configuration and all associated codes.
operationId: getConfigurationExport
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
responses:
'200':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/test:
post:
tags:
- configurations
summary: Run Configuration Test
description: "Runs an inline test of a given configuration against an eICR/RR pair.\n\nThis endpoint orchestrates the validation and refinement process by:\n1. Handling file input, either from a user upload or a default sample file.\n2. Calling the `inline_testing` service, which validates that the specified\n configuration's condition is reportable in the provided file.\n3. Handling the service response:\n - If validation fails, raises a 400 Bad Request with a specific error.\n - If successful, proceeds with the returned refined document.\n4. Packaging the original eICR, RR, and the single refined eICR into a\n new in-memory zip archive.\n5. Uploading the archive to S3 and generating a pre-signed download URL.\n6. Returning a `ConfigurationTestResponse` with the download URL and details\n of the successful refinement.\n\nArgs:\n id: The ID of the configuration to test.\n uploaded_file: An optional user-provided zip file with an eICR and RR.\n create_output_zip: Dependency to create a zip archive in memory.\n upload_zip: Dependency to upload the archive to S3.\n user: The authenticated user making the request.\n db: The database connection.\n sample_zip_path: Path to the default sample zip file.\n logger: The application logger.\n\nReturns:\n A response object containing the original eICR, a URL to download the\n zipped results, and details about the refined condition."
operationId: runInlineConfigurationTest
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_runInlineConfigurationTest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationTestResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/sections:
post:
tags:
- configurations
summary: Insert Custom Section
description: "Create a new custom section for a given configuration ID.\n\nArgs:\n configuration_id (UUID): The ID of the configuration\n section_input (CustomSectionInput): Desired properties of the section\n user (DbUser): The logged-in user\n db (AsyncDatabaseConnection): The database connection"
operationId: addCustomSection
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddSectionInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: string
title: Response Addcustomsection
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- configurations
summary: Delete Custom Section
description: "Delete a custom section.\n\nArgs:\n configuration_id (UUID): ID of the configuration with custom section to delete\n section_input (DeleteCustomSectionInput): Custom section deletion input\n user (DbUser): The logged in user\n db (AsyncDatabaseConnection): The database connection\n\nRaises:\n HTTPException: 404 if configuration isn't found\n HTTPException: 409 if configuration isn't a draft\n HTTPException: 404 if custom section code to delete isn't found\n\nReturns:\n str: Deleted custom section code"
operationId: deleteCustomSection
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSectionInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: string
title: Response Deletecustomsection
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- configurations
summary: Update Section
description: "Update a section entry for a configuration.\n\nArgs:\n configuration_id (UUID): ID of the configuration to update\n section_input (SectionUpdateInput): Updated section info\n user (DbUser): The logged-in user\n db (AsyncDatabaseConnection): Database connection\n\nRaises:\n HTTPException: 400 if the code is not valid, code is in use, or name is in use\n HTTPException: 404 if configuration isn't found\n HTTPException: 409 if configuration is not a draft and therefore not editable\n HTTPException: 500 if section processing can't be updated\n\nReturns:\n UpdateSectionProcessingResponse: The message to show the user"
operationId: updateSection
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SectionUpdateInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSectionProcessingResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/activate:
patch:
tags:
- configurations
summary: Activate Configuration
description: "Activate the specified configuration.\n\nArgs:\n configuration_id (UUID): ID of the configuration to update\n user (DbUser): The logged-in user\n logger (Logger): The standard logger\n db (AsyncDatabaseConnection): Database connection\n\nRaises:\n HTTPException: 400 if configuration can't be activated because of its current state\n HTTPException: 404 if configuration can't be found\n HTTPException: 500 if configuration can't be activated by the server\n\nReturns:\n ActivateConfigurationResponse: Metadata about the activated condition for confirmation"
operationId: activateConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationStatusUpdateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/deactivate:
patch:
tags:
- configurations
summary: Deactivate Configuration
description: "Deactivate the specified configuration.\n\nArgs:\n configuration_id (UUID): ID of the configuration to update\n user (DbUser): The logged-in user\n logger (Logger): The standard application logger\n db (AsyncDatabaseConnection): Database connection\n\nRaises:\n HTTPException: 400 if configuration can't be deactivated because of its current state\n HTTPException: 404 if configuration can't be found\n HTTPException: 500 if configuration can't be deactivated by the server\n\nReturns:\n ConfigurationStatusUpdateResponse: Metadata about the activated condition for confirmation"
operationId: deactivateConfiguration
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationStatusUpdateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/configurations/{configuration_id}/release-lock:
post:
tags:
- configurations
summary: Release Configuration Lock
description: "Release config lock if held by user.\n\nArgs:\n configuration_id (UUID): ID of the configuration to update\n user (DbUser): The logged-in user\n db (AsyncDatabaseConnection): Database connection"
operationId: releaseConfigurationLock
parameters:
- name: configuration_id
in: path
required: true
schema:
type: string
format: uuid
title: Configuration Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
CodeSystemKey:
type: string
ConfigurationStatusUpdateResponse:
properties:
configuration_id:
type: string
format: uuid
title: Configuration Id
status:
$ref: '#/components/schemas/DbConfigurationStatus'
type: object
required:
- configuration_id
- status
title: ConfigurationStatusUpdateResponse
description: Response model for updating the status a configuration.
SectionUpdateInput:
properties:
include:
anyOf:
- type: boolean
- type: 'null'
title: Include
narrative:
anyOf:
- $ref: '#/components/schemas/DbNarrativeAction'
- type: 'null'
action:
anyOf:
- $ref: '#/components/schemas/DbSectionAction'
- type: 'null'
name:
anyOf:
- type: string
- type: 'null'
title: Name
current_code:
type: string
title: Current Code
new_code:
anyOf:
- type: string
- type: 'null'
title: New Code
type: object
required:
- current_code
title: SectionUpdateInput
description: Input model for updating a section's processing instructions.
DeleteSectionInput:
properties:
code:
type: string
title: Code
type: object
required:
- code
title: DeleteSectionInput
description: Request body to delete a section.
ConfirmUploadCustomCodesInput:
properties:
custom_codes:
items:
$ref: '#/components/schemas/UploadCustomCodesPreviewItem'
type: array
title: Custom Codes
type: object
required:
- custom_codes
title: ConfirmUploadCustomCodesInput
description: Payload used to confirm a previously validated CSV import.
CodeSystemIndex:
additionalProperties:
$ref: '#/components/schemas/DbCodeSystem'
propertyNames:
$ref: '#/components/schemas/CodeSystemKey'
type: object
CreateConfigurationResponse:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
type: object
required:
- id
- name
title: CreateConfigurationResponse
description: Configuration creation response model.
UploadCustomCodesResponse:
properties:
message:
anyOf:
- type: string
- type: 'null'
title: Message
codes_processed:
anyOf:
- type: integer
- type: 'null'
title: Codes Processed
total_custom_codes_in_configuration:
anyOf:
- type: integer
- type: 'null'
title: Total Custom Codes In Configuration
errors:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Errors
type: object
title: UploadCustomCodesResponse
description: CSV response model. Errors are surfaced via the `errors` array.
DbCodeSystem:
properties:
id:
type: string
format: uuid
title: Id
key:
$ref: '#/components/schemas/CodeSystemKey'
display_name:
type: string
title: Display Name
oid:
type: string
title: Oid
type: object
required:
- id
- key
- display_name
- oid
title: DbCodeSystem
description: A code system row from the `systems` table.
DbTotalConditionCodeCount:
properties:
condition_id:
type: string
format: uuid
title: Condition Id
display_name:
type: string
title: Display Name
total_codes:
type: integer
title: Total Codes
type: object
required:
- condition_id
- display_name
- total_codes
title: DbTotalConditionCodeCount
description: Total code count model.
ConfigurationTestResponse:
properties:
original_eicr:
type: string
title: Original Eicr
refined_download_key:
type: string
title: Refined Download Key
condition:
$ref: '#/components/schemas/Condition'
type: object
required:
- original_eicr
- refined_download_key
- condition
title: ConfigurationTestResponse
description: Model to represent the response provided to the client when in-line testing is run.
UploadCustomCodesCsvInput:
properties:
csv_text:
type: string
title: Csv Text
description: Full CSV contents as UTF-8 text
filename:
anyOf:
- type: string
- type: 'null'
title: Filename
type: object
required:
- csv_text
title: UploadCustomCodesCsvInput
description: Input model for Custom Code CSV.
UpdateCustomCodeInput:
properties:
system_key:
type: string
title: System Key
code:
type: string
title: Code
name:
type: string
title: Name
new_code:
anyOf:
- type: string
- type: 'null'
title: New Code
new_system_key:
anyOf:
- type: string
- type: 'null'
title: New System Key
new_name:
anyOf:
- type: string
- type: 'null'
title: New Name
type: object
required:
- system_key
- code
- name
- new_code
- new_system_key
- new_name
title: UpdateCustomCodeInput
description: Input model when updating a config's custom code.
GetConfigurationsResponse:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
status:
$ref: '#/components/schemas/DbConfigurationStatus'
type: object
required:
- id
- name
- status
title: GetConfigurationsResponse
description: Model for a user-defined configuration.
ConfigurationCustomCodeResponse:
properties:
id:
type: string
format: uuid
title: Id
display_name:
type: string
title: Display Name
code_sets:
items:
$ref: '#/components/schemas/DbTotalConditionCodeCount'
type: array
title: Code Sets
custom_codes:
items:
$ref: '#/components/schemas/DbConfigurationCustomCode'
type: array
title: Custom Codes
type: object
required:
- id
- display_name
- code_sets
- custom_codes
title: ConfigurationCustomCodeResponse
description: Configuration response for custom code operations (add/edit/delete).
DbConfigurationSectionProcessing:
properties:
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cdc/refs/heads/main/openapi/cdc-configurations-api-openapi.yml