CDC configurations API
The configurations API from CDC — 15 operation(s) for configurations.
OpenAPI Specification
openapi: 3.1.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
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:
DbSectionType:
type: string
enum:
- standard
- custom
NarrativeOnlySection:
type: string
enum:
- 10154-3
- 29299-5
- 10164-2
- 10187-3
title: NarrativeOnlySection
description: 'These sections have no entry match rules in the eICR specification.
They are conveyed via the narrative block only. Configuring them for
"refine" is meaningless (there is nothing to match against), so the UI
disables the refine toggle for them and the refinement plan normalizes
"refine" -> "retain" for these codes (see refine.py). The Enum values
remain the single source of truth shipped to the frontend. A unit test
guards that this enum stays in sync with the spec catalog (every code
listed here has has_match_rules=False in the catalog, and every catalog
section with has_match_rules=False is listed here).'
UploadCustomCodesPreviewResponse:
properties:
preview:
items:
$ref: '#/components/schemas/UploadCustomCodesPreviewItem'
type: array
title: Preview
code_systems:
$ref: '#/components/schemas/CodeSystemIndex'
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
type: object
required:
- preview
- code_systems
title: UploadCustomCodesPreviewResponse
description: Validated CSV preview for delayed confirmation; only valid if preview.
CustomCodes:
properties:
codes:
items:
$ref: '#/components/schemas/DbConfigurationCustomCode'
type: array
title: Codes
code_systems:
$ref: '#/components/schemas/CodeSystemIndex'
type: object
required:
- codes
- code_systems
title: CustomCodes
description: Model for custom codes response, with systems bundled alongside codes for frontend display.
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.
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.
DbNarrativeAction:
type: string
enum:
- retain
- remove
- reconstruct
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).
UploadCustomCodesPreviewItem:
properties:
code:
type: string
title: Code
system_key:
type: string
title: System Key
system_display_name:
type: string
title: System Display Name
name:
type: string
title: Name
row:
anyOf:
- type: integer
- type: 'null'
title: Row
type: object
required:
- code
- system_key
- system_display_name
- name
title: UploadCustomCodesPreviewItem
description: Validated CSV row ready for confirmation.
Body_runInlineConfigurationTest:
properties:
id:
type: string
format: uuid
title: Id
uploaded_file:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Uploaded File
type: object
required:
- id
title: Body_runInlineConfigurationTest
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.
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.
IncludedCondition:
properties:
id:
type: string
format: uuid
title: Id
display_name:
type: string
title: Display Name
canonical_url:
type: string
title: Canonical Url
version:
type: string
title: Version
associated:
type: boolean
title: Associated
type: object
required:
- id
- display_name
- canonical_url
- version
- associated
title: IncludedCondition
description: Model for a condition that is associated with a configuration.
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.
AssociateCodesetInput:
properties:
condition_id:
type: string
format: uuid
title: Condition Id
type: object
required:
- condition_id
title: AssociateCodesetInput
description: Condition association input model.
LockedByUser:
properties:
id:
type: string
format: uuid
# --- 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