Data Portability

Export your organization's data at any time. We support selective, app-by-app export across all major data classes, plus FHIR-compliant clinical bulk export for healthcare customers.

Quick start

What you can export:

• Document originals (PDF, Word, Excel, images, etc.)
• Clinical data (FHIR-compliant NDJSON)
• Training datasets (JSONL for ML pipelines)
• Audit logs (CSV, up to 10,000 records per request)
• Project data (PMO tasks, projects, ITSM tickets — CSV)
• Compliance artifacts (GDPR RoPA, transfer registers, data-flow diagrams)

Export surfaces — at a glance

All exports are audit-logged. Files generated by async jobs auto-expire 24 hours after completion.

Per-surface guides

1. Documents — download originals

Download any document you uploaded to Cognethics in its original format.

Endpoint: GET /api/documents/{document_id}/download/

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.cognethics.com/api/documents/550e8400-e29b-41d4-a716-446655440000/download/"

Response: File stream (PDF, DOCX, XLSX, PNG, JPG, etc.).

Query parameters:

• inline (boolean, default: false) — true for inline (browser view), false for attachment (force download).

Notes:

• All downloads are audit-logged for compliance.
• Cryptographic proof-of-download recorded in the audit log for every file.
• Bulk download: POST /api/documents/sharepoint/items/bulk/download-zip/ returns a ZIP archive across multiple documents.

2. FHIR bulk clinical export

Export FHIR-compliant clinical records (Patient, Observation, DiagnosticReport, etc.) for integration with other health systems.

Kickoff: POST /api/ehr/fhir/r4/$export (or GET with query params) Status poll: GET /api/ehr/fhir/r4/$export-status/{job_id} Download: GET /api/ehr/fhir/r4/$export-file/{job_id}/{filename}

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/fhir+json" \
  "https://api.cognethics.com/api/ehr/fhir/r4/\$export" \
  -d '{
    "_type": "Patient,Observation,DiagnosticReport",
    "_since": "2026-01-01T00:00:00Z"
  }'

Response (kickoff): 202 Accepted with a Content-Location header pointing at the status endpoint.

Query parameters:

• _type — comma-separated FHIR resource types (e.g., Patient,Observation,Medication).
• _since — ISO 8601 timestamp (e.g., 2026-01-01T00:00:00Z) to limit to records modified after this date.
• _typeFilter — per-type search parameters (e.g., Observation?code=12345).

Format: NDJSON (newline-delimited JSON, one resource per line). JSON available on request.

Compliance:

• FHIR Bulk Data Access IG 2.0 conformant.
• ONC Cures Act g(10) compliant.
• HIPAA-eligible (included in BAA).
• 24-hour file retention.

3. GDPR compliance exports (RoPA, transfers, data inventory)

Export Article 30 Records of Processing Activities, transfer registers, and data inventories for compliance audits and cross-border transfer documentation.

Endpoint: POST /api/v1/data-mapping/exports/ (convenience endpoints: /api/v1/data-mapping/exports/ropa/ and /api/v1/data-mapping/exports/assets/).

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  -H "Content-Type: application/json" \
  "https://api.cognethics.com/api/v1/data-mapping/exports/" \
  -d '{
    "export_type": "ropa_pdf",
    "parameters": {
      "include_data_flows": true,
      "include_transfers": true,
      "include_ai_systems": true,
      "language": "en"
    }
  }'

Export types:

• ropa_pdf / ropa_excel — Article 30 Record of Processing Activities.
• data_inventory_excel / data_inventory_csv — data asset inventory.
• transfer_register_pdf / transfer_register_excel — cross-border transfer register.
• data_flow_png / data_flow_svg — data-flow diagrams.

Status polling:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  "https://api.cognethics.com/api/v1/data-mapping/exports/{export_id}/status/"

Returns JSON with status (pending / processing / completed / failed / expired) and progress (0–100%).

Download (once ready):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  "https://api.cognethics.com/api/v1/data-mapping/exports/{export_id}/download/" \
  --output export.pdf

Caps:

• 24-hour expiry after completion.
• Org-scoped (only accessible by org admins).
• Async Celery job — poll for progress.
• Automatic cleanup of expired files.

4. Training datasets (JSONL export)

Export training datasets in JSONL (JSON Lines) format for machine learning pipelines, data science tools, or external annotation platforms.

Endpoint: POST /api/training_data/datasets/{dataset_id}/export/

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.cognethics.com/api/training_data/datasets/dataset-uuid-123/export/" \
  -d '{"format": "jsonl"}'

Response: 202 Accepted with export_id.

{
  "export_id": "export-uuid-456",
  "status": "pending",
  "created_at": "2026-05-21T12:34:56Z"
}

JSONL output (each line):

{"id": "anno-1", "text": "...", "label": "label-name", "tags": [], "metadata": {}}
{"id": "anno-2", "text": "...", "label": "label-name", "tags": [], "metadata": {}}

Notes:

• SOC 2 audit-logged.
• Async Celery job — fetch status via the dataset export endpoint.
• Training-data-app scoped.

5. Audit logs (CSV export)

Export your organization's audit trail for compliance reviews, incident investigations, and regulatory audits.

Endpoint: GET /api/core/audit/export/?format=csv

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-Context: org-uuid-123" \
  "https://api.cognethics.com/api/core/audit/export/?format=csv&limit=5000&start_date=2026-05-01"

Response: CSV file (text/csv).

CSV headers:

Timestamp,Category,Action,Entity Type,Entity ID,User Email,User Name,IP Address,Request Method,Request Path,Response Status,Changes

Query parameters:

• format — currently only csv is supported.
• action — filter by action (create, update, delete, view, etc.).
• entity_type — filter by entity (document, claim, user, etc.).
• category — filter by category.
• user_id — filter by user UUID.
• start_date, end_date — date range (YYYY-MM-DD).
• limit — max records to return (default 1,000, max 10,000).

Caps:

• Hard limit: 10,000 records per export. For larger audits, page through with date-range filters and make multiple requests.
• Org-scoped (only your org's logs).

6. MCP API loop — export any entity type

The MCP API exposes paginated read access to every entity type in the system. Loop through entity types with pagination to export custom data subsets.

Pattern: call prism_entity_crud(app="...", entity="...", operation="list", page=1, page_size=100, filters={...}) and paginate until you receive fewer than page_size records.

from anthropic import Anthropic

client = Anthropic()

entity_types = [
    ("healthcare", "claim"),
    ("finance", "invoice"),
    ("hr", "employee"),
    ("documents", "document"),
]

all_data = {}

for app, entity in entity_types:
    all_data[entity] = []
    page = 1

    while True:
        response = client.beta.messages.create(
            model="claude-opus-4-7",
            messages=[{
                "role": "user",
                "content": (
                    f"List {entity} records from {app}, page {page}, "
                    f"100 per page. Return raw JSON list."
                ),
            }],
            betas=["mcp-1.0"],
        )

        records = parse_response(response)
        all_data[entity].extend(records)

        if len(records) < 100:
            break
        page += 1

import json
with open("export.json", "w") as f:
    json.dump(all_data, f, indent=2)

Pagination rules:

• Default page size: 50.
• Max page size: 100 (hard cap).
• To export N records: make ceil(N / 100) API calls.

Supported filters:

• date_range — start and end timestamps.
• status — e.g., pending, completed, failed.
• owner — user ID or email.
• Custom fields per entity type.

Response format: JSON array of entity objects.

7. Scheduled exports — run on a cron

Any of the compliance export surfaces above (RoPA, data inventory, transfer register, data-flow diagrams) can be run on a recurring schedule. Cognethics scans schedules every minute and enqueues a fresh export job whenever a schedule comes due. Each run produces a normal ExportTask with the standard 24-hour download window — plus optional notifications and remote-destination delivery.

Create a schedule:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  -H "Content-Type: application/json" \
  "https://api.cognethics.com/api/v1/data-mapping/schedules/" \
  -d '{
    "name": "Daily RoPA snapshot",
    "description": "Article 30 record refreshed every morning at 06:00 UTC",
    "export_type": "ropa_pdf",
    "schedule_cron": "0 6 * * *",
    "parameters": {
      "include_data_flows": true,
      "include_transfers": true,
      "language": "en"
    },
    "notification_emails": ["[email protected]"]
  }'

Body parameters:

• name — human-readable label.
• export_type — any value from the export-types table above.
• schedule_cron — standard 5-field cron expression in UTC. Examples below.
• parameters — same filter parameters you would pass to a one-shot export.
• destination (optional) — UUID of an ExportDestination (S3 / SFTP). Omit for download-link-only delivery.
• notification_emails (optional) — list of recipients to ping when each run completes.

Cron examples (UTC):

Manage a schedule:

# List your org's schedules
GET    /api/v1/data-mapping/schedules/

# Inspect one
GET    /api/v1/data-mapping/schedules/{id}/

# Edit (cron, parameters, destination, notification list, etc.)
PATCH  /api/v1/data-mapping/schedules/{id}/

# Temporarily turn it off without deleting
POST   /api/v1/data-mapping/schedules/{id}/disable/

# Re-enable (recomputes next_run_at relative to now)
POST   /api/v1/data-mapping/schedules/{id}/enable/

# Force a run on the next scanner tick (≤ 60s away)
POST   /api/v1/data-mapping/schedules/{id}/run-now/

# Delete permanently
DELETE /api/v1/data-mapping/schedules/{id}/

Telemetry on each schedule:

• last_run_at — UTC timestamp of the last successful dispatch.
• next_run_at — when the scanner will fire it next.
• run_count / failure_count — lifetime counters.
• last_export_task — UUID of the most recent ExportTask so you can download or audit the result.

Permissions:

Reads (list, retrieve) require any authenticated user with org context. Mutations (create, edit, enable/disable, delete) require the data_mapping.manage_export_schedules permission. Org administrators have this by default; grant it to other roles via the admin console.

Audit: every dispatch logs an AuditService.log_data_export entry tagged with the schedule UUID, so a scheduled run is indistinguishable from a manual export in your audit trail — just attributed to the schedule's creator.

8. Bring your own destination — S3 or SFTP

Any export (manual or scheduled) can be delivered straight to your own S3 bucket or SFTP server in addition to the Cognethics-hosted download link. Credentials are encrypted at rest with Fernet — only the running export worker can decrypt them — and we never echo secrets back through the API.

Create a destination:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  -H "Content-Type: application/json" \
  "https://api.cognethics.com/api/v1/data-mapping/destinations/" \
  -d '{
    "name": "Audit S3 bucket",
    "kind": "s3",
    "config": {
      "bucket": "acme-cognethics-exports",
      "prefix": "exports/",
      "region": "us-east-1"
    },
    "credentials": {
      "access_key_id": "AKIA...",
      "secret_access_key": "..."
    }
  }'

S3 fields:

• config.bucket (required), config.prefix (optional), config.region (optional), config.endpoint_url (optional — point at non-AWS S3-compatible endpoints like MinIO).
• credentials.access_key_id (required), credentials.secret_access_key (required), credentials.session_token (optional, for STS).

SFTP fields:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  -H "Content-Type: application/json" \
  "https://api.cognethics.com/api/v1/data-mapping/destinations/" \
  -d '{
    "name": "Partner SFTP",
    "kind": "sftp",
    "config": {
      "host": "sftp.partner.example",
      "port": 22,
      "user": "cognethics",
      "path": "/inbox/exports"
    },
    "credentials": {
      "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
      "key_passphrase": "optional"
    }
  }'

• config.host, config.user (both required), config.port (default 22), config.path (remote directory; created on first use).
• credentials.private_key (PEM/OpenSSH; RSA, Ed25519, or ECDSA) OR credentials.password.

Optional GPG signing — supply gpg_recipient_fingerprint and gpg_public_key (ASCII-armored) on the destination. Each export is GPG-encrypted to that recipient before upload, and lands at the destination with a .gpg suffix.

Use a destination on a one-shot export:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org-uuid-123" \
  -H "Content-Type: application/json" \
  "https://api.cognethics.com/api/v1/data-mapping/exports/" \
  -d '{
    "export_type": "ropa_pdf",
    "destination": "destination-uuid-from-above"
  }'

The Celery worker writes the file to local storage as usual (so the standard 24-hour download URL still works), then uploads it to the destination. The export task gains remote_uri, delivered_at, and delivery_error fields.

Verify a destination works before using it:

POST /api/v1/data-mapping/destinations/{id}/test/

Writes a small probe file to the destination and deletes it afterwards. Returns {"ok": true, "remote_uri": "..."} on success; {"ok": false, "error": "..."} on failure.

Manage destinations:

GET    /api/v1/data-mapping/destinations/                # list
GET    /api/v1/data-mapping/destinations/{id}/           # detail (no secrets)
PATCH  /api/v1/data-mapping/destinations/{id}/           # update (omit credentials to keep existing)
DELETE /api/v1/data-mapping/destinations/{id}/           # remove

Permissions: reads require any authenticated user with org context. Mutations require the data_mapping.manage_export_destinations permission. Org administrators have it by default.

Security: credentials are encrypted at rest with a key derived from the Cognethics master secret via HKDF; the encrypted blob is the only field stored in the database. Decryption happens only inside the Celery export worker for the duration of an upload. The API never returns plaintext credentials — even to the user who created them.

Data portability for GDPR & privacy compliance

Your rights

• GDPR Article 15 (Right of Access) — confirmation that we process your personal data, plus a copy.
• GDPR Article 20 (Right to Data Portability) — receive personal data you provided in a structured, machine-readable format, and transmit it to another organization.
• GDPR Article 17 (Right to Erasure) — request deletion of personal data under certain conditions.

How to submit a request

For data subject access requests (DSAR), right to erasure, or other privacy requests, submit the form below. In your message, include:

• Your full name and email address.
• Your organization name (if applicable).
• Specific request type (access, portability, erasure, correction, restrict, object, withdraw consent).
• Date range of data (if applicable).

Response SLA: 30 days (GDPR Article 12(3)).

What happens next

1. We verify your identity and your right to request data for the specified organization.
2. We compile all relevant data exports (documents, audit logs, structured records) into a secure archive.
3. We encrypt and deliver via secure presigned link (48-hour expiry).
4. You download and retain your copy.
5. For erasure requests, we execute and confirm hard-deletion within 30 days of approval.

FAQs

How long do exported files stay available? Files expire 24 hours after async-job completion (FHIR, RoPA, training datasets). Download them within that window or request a new export.

What if I need more than 10,000 audit log records? Use date-range filters and make multiple requests. For very large audits, reach our support team through the contact form and we can arrange a custom export.

Can I automate exports on a schedule? Yes. Create an ExportSchedule against /api/v1/data-mapping/schedules/ with a standard cron expression (UTC). The scanner runs every minute, so a daily, weekly, monthly, or sub-hourly cadence all work. See Scheduled exports above for the full API.

Are all exports encrypted? All data in transit (HTTPS/TLS) is encrypted. Files at rest are encrypted on our storage. For DSAR responses, we use additional encryption for the download link.

Can I export data for a sub-organization or department? Exports are scoped to your organization. Sub-org exports require a separate request with appropriate permissions.

What formats does Cognethics support? CSV, JSON, JSONL, PDF, Excel, NDJSON (FHIR), and original document formats (DOCX, XLSX, images, etc.).

Support

For questions about data export, GDPR compliance, or HIPAA BAA portability, reach our support team through the contact form.