Export records from the REDCap project.

Args: fields: Specific field names to export. None exports all fields. records: Specific record IDs to export. None exports all records. events: Specific event names to export (longitudinal projects only). raw_or_label: 'raw' for coded values, 'label' for choice labels. export_checkbox_label: Export checkbox field labels instead of 0/1. limit: Maximum number of records to return (default 1000).

Returns: JSON array of records.

Import records into the REDCap project.

Args: data: JSON array string of records to import. Each record must include the project's record ID field.

Returns: Confirmation message with the count of imported records.

Delete records from the REDCap project by record ID.

Args: record_ids: List of record IDs to delete.

Returns: Confirmation message with the count of deleted records.

Export a saved REDCap report by its ID.

Args: report_id: The numeric ID of the report (visible in the REDCap URL when viewing the report).

Returns: JSON array of report rows.

Export the list of export field names for the project.

Checkbox fields have different export names (e.g. 'chk___1', 'chk___2') than their original field name. Use this to resolve the correct names before exporting or referencing checkbox data.

Args: field: Filter to a specific field name. None returns all fields.

Returns: JSON array of objects with original_field_name and export_field_name.

Generate the next available record name for the project.

Use this before importing a new record to obtain a valid, unused record ID that respects the project's auto-numbering scheme.

Returns: The next record name as a string.

Get information about the REDCap project.

Returns project title, PI name, creation time, record count, and other project-level settings.

Returns: JSON object with project metadata.

Get the data dictionary (metadata) for the REDCap project.

Returns field definitions including type, label, choices, validation, branching logic, and required status.

Args: fields: Filter to specific field names. None returns all fields. forms: Filter to specific instrument/form names. None returns all forms.

Returns: JSON array of field definitions.

Export the audit log for the REDCap project.

Args: log_type: Filter by event type. One of: 'export', 'manage', 'user', 'record', 'record_add', 'record_edit', 'record_delete', 'lock_record', 'page_view'. None returns all types. user: Filter to a specific REDCap username. record: Filter to a specific record ID. begin_time: Start of date range as ISO 8601 string (e.g. '2024-01-01T00:00:00'). end_time: End of date range as ISO 8601 string.

Returns: JSON array of log entries.

Export the repeating instruments and events configuration.

Requires REDCap 6.16 or later. Returns an error message on older instances.

Returns: JSON array of repeating instrument/event definitions, or an empty array if the project has no repeating instruments or events.

Import (create or update) repeating instruments and events configuration.

Requires REDCap 6.16 or later. Returns an error message on older instances.

Args: data: JSON array of repeating instrument/event objects. Each object should have event_name, form_name, and custom_form_label fields.

Returns: Confirmation message with the count of imported definitions.

Get the list of instruments (forms/surveys) in the REDCap project.

Returns: JSON array of instruments with their internal names and display labels.

Get the mapping of instruments to events (longitudinal projects only).

Returns: JSON array of arm/event/instrument mappings, or an error message if the project is not longitudinal.

Add a new instrument (form) to the project.

Creates the instrument by inserting a placeholder descriptive field. REDCap requires at least one field per instrument; the placeholder can be removed later once real fields have been added via add_field.

Note: the instrument display label defaults to the prettified form_name and can only be changed in the REDCap UI (Designer → instrument name).

Args: form_name: Internal name for the instrument (lowercase, underscores, no spaces).

Returns: Confirmation message with the placeholder field name.

Delete an instrument and all its fields from the project.

Removes every field that belongs to the instrument. REDCap will reject the operation if the instrument contains the record-ID field.

Args: form_name: Internal name of the instrument to delete.

Returns: Confirmation message with the count of removed fields.

Rename an instrument by updating the form_name on all its fields.

Note: this changes the internal name only. The display label shown in the REDCap UI must be updated separately in Designer.

Args: old_form_name: Current internal name of the instrument. new_form_name: New internal name (lowercase, underscores, no spaces).

Returns: Confirmation message with the count of updated fields.

Move a field to a new position in the data dictionary.

Field order controls the layout of data-entry screens and surveys.

Args: field_name: Variable name of the field to move. after_field: Move the field immediately after this field name. If None, the field is moved to the end of its own instrument.

Returns: Confirmation message.

Clone all fields of an instrument into a new instrument.

Each cloned field name is prefixed with field_prefix to avoid collisions. Branching logic is cleared on cloned fields because it references the original field names; update it manually with update_field after cloning.

Args: source_form: Internal name of the instrument to clone. new_form_name: Internal name for the new instrument. field_prefix: Prefix to prepend to every cloned field name (e.g. 'v2_' turns 'age' into 'v2_age').

Returns: Confirmation message with the count of cloned fields.

Assign an instrument to an event in a longitudinal project.

Args: instrument: Internal form name of the instrument. event: Unique event name (e.g. 'baseline_arm_1'). arm_num: Arm number the event belongs to (default 1).

Returns: Confirmation message, or an error if the project is not longitudinal.

Remove an instrument from an event in a longitudinal project.

Args: instrument: Internal form name of the instrument. event: Unique event name (e.g. 'baseline_arm_1').

Returns: Confirmation message, or an error if the mapping did not exist.

Add a new field to an existing instrument.

Exports the current data dictionary, inserts the new field, and imports the updated dictionary back. The operation is atomic from REDCap's perspective.

Args: form_name: Internal name of the instrument to add the field to. field_name: Variable name for the new field (lowercase, underscores, no spaces). field_type: One of: text, notes, calc, radio, checkbox, yesno, truefalse, select, slider, file, descriptive. field_label: Display label shown to data-entry users. choices: Choice definitions for radio/checkbox/select fields, formatted as "1, Label 1 | 2, Label 2". Ignored for other types. required: Whether the field must be filled before saving the record. branching_logic: Show/hide logic expression (e.g. "[age] > 18"). field_note: Helper text displayed below the field. section_header: Section header to display above this field. validation: Validation type for text fields (e.g. integer, number, date_ymd, email, phone). validation_min: Minimum allowed value (for validated text fields). validation_max: Maximum allowed value (for validated text fields). field_annotation: REDCap action tags and annotations (e.g. @HIDDEN). after_field: Insert the new field immediately after this field name. If None, the field is appended at the end of the instrument.

Returns: Confirmation message with the count of updated fields.

Remove a field from the project data dictionary.

Exports the current data dictionary, removes the field, and imports the updated dictionary back.

Note: REDCap will reject the removal of the record-ID field and may reject removals that would break branching logic or calculated fields in other instruments.

Args: field_name: Variable name of the field to remove.

Returns: Confirmation message, or an error if the field was not found.

Update properties of an existing field in the data dictionary.

Only the properties you pass will be changed; all other properties are preserved exactly as they are. Exports the full dictionary, patches the target field, and imports it back.

Args: field_name: Variable name of the field to update. field_label: New display label. field_note: New helper text shown below the field. required: Set to True to make the field required, False to make it optional. branching_logic: New show/hide logic expression. choices: New choice definitions for radio/checkbox/select fields, formatted as "1, Label 1 | 2, Label 2". validation: New validation type for text fields. validation_min: New minimum allowed value. validation_max: New maximum allowed value. field_annotation: New action tags and annotations. section_header: New section header above this field.

Returns: Confirmation message, or an error if the field was not found.

Export a file attachment from a REDCap record field.

Args: record: Record ID containing the file. field: Name of the file upload field. event: Event name (longitudinal projects only). repeat_instance: Repeat instance number for repeating instruments/events.

Returns: JSON object with base64-encoded file content, filename, and content type.

Import (upload) a file into a REDCap record field.

Args: record: Record ID to attach the file to. field: Name of the file upload field. file_name: Name to give the file in REDCap. content_base64: Base64-encoded file content. event: Event name (longitudinal projects only). repeat_instance: Repeat instance number for repeating instruments/events.

Returns: Confirmation message.

Delete a file attachment from a REDCap record field.

Args: record: Record ID containing the file. field: Name of the file upload field. event: Event name (longitudinal projects only).

Returns: Confirmation message.

Export a PDF of one or all instruments for a record.

Args: record: Record ID to export. None exports all records (use with caution). event: Event name (longitudinal projects only). instrument: Specific instrument to export. None exports all instruments. repeat_instance: Repeat instance number for repeating instruments/events. compact_display: If True, uses compact PDF layout.

Returns: JSON object with base64-encoded PDF content.

Export arms for a longitudinal REDCap project.

Args: arms: Specific arm numbers to export. None exports all arms.

Returns: JSON array of arms with arm_num and name fields.

Import (create or update) arms in a longitudinal REDCap project.

Args: data: JSON array of arm objects, each with arm_num and name fields. override: If True, existing arms not in the import will be deleted.

Returns: Confirmation message with the count of imported arms.

Delete arms from a longitudinal REDCap project.

Args: arms: List of arm numbers to delete.

Returns: Confirmation message with the count of deleted arms.

Export events for a longitudinal REDCap project.

Args: arms: Filter to specific arm numbers. None exports events for all arms.

Returns: JSON array of events with event_name, arm_num, day_offset, and other fields.

Import (create or update) events in a longitudinal REDCap project.

Args: data: JSON array of event objects with event_name, arm_num, day_offset, etc. override: If True, existing events not in the import will be deleted.

Returns: Confirmation message with the count of imported events.

Delete events from a longitudinal REDCap project.

Args: events: List of unique event names to delete.

Returns: Confirmation message with the count of deleted events.

Get a unique survey link for a participant to complete an instrument.

The instrument must be enabled as a survey in REDCap. Returns an error if surveys are not enabled or the instrument is not a survey.

Args: record: Record ID of the participant. instrument: Internal name of the survey instrument. event: Event name (longitudinal projects only). repeat_instance: Repeat instance number (default 1).

Returns: The survey URL as a plain string.

Export the list of survey participants for an instrument.

The instrument must be enabled as a survey in REDCap. Returns an error if surveys are not enabled or the instrument is not a survey.

Args: instrument: Internal name of the survey instrument. event: Event name (longitudinal projects only).

Returns: JSON array of participant records with email, name, and response status.

Return a compact structural overview of the REDCap project.

Useful as a first call when starting work on an existing project. Returns instruments with field counts and type breakdowns. For longitudinal projects, includes the full event/instrument matrix.

Returns: JSON object describing the project structure.

Find every field that references a given field in branching logic or calculations.

Run this before removing or renaming a field to avoid breaking the project. Returns all fields whose branching_logic or calculated formula reference field_name.

Args: field_name: Variable name to search for.

Returns: JSON object with a list of referencing fields, or a confirmation that no references exist.

Scan all branching logic expressions for references to non-existent fields.

Checks every field's branching_logic for [field_name] tokens that do not match any field in the data dictionary. For longitudinal projects, event names in [event_name][field_name] syntax are excluded from the check.

Returns: A confirmation message if all references are valid, or a JSON object listing every broken reference with its location.