Import and export

#imports_inspect

stable added in 0.2.0-alpha.5 read-only

Inspect an uploaded file (by upload_id or file_id): columns, row count, detected types, empty and duplicate counts, suggested match keys and preview rows. Pass object to compare the columns with that object's fields (enum values included), and links to compare link columns with the target's unique values. value_suggestions lists values that differ from enum/status values or link targets by spacing, case, accents, punctuation (or a legal suffix for link names), with level and certainty, plus values with no match. suggested_normalize holds only unambiguous mappings; uncertain_normalize must be reviewed with the user (imports_run needs confirm_uncertain for those). Show them before using any. Pass match_on to check its column: match_key_case_variants lists key values that differ only by case or spacing (use match_fold). columns names may differ from the header in case; column_matches says which header matched. Read-only.

MCP tool

imports_inspect

REST

POST /v1/workspaces/{ws}/imports/inspect scope records:read

Arguments

Example

upload_id comes from imports_start, after the file was uploaded to its upload_url.

{
  "tool": "imports_inspect",
  "arguments": {
    "upload_id": "upl_example",
    "object": "contact",
    "match_on": "email"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "imports_inspect",
    "arguments": {
      "upload_id": "upl_example",
      "object": "contact",
      "match_on": "email"
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/imports/inspect" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_example","object":"contact","match_on":"email"}'

#imports_run

stable added in 0.2.0-alpha.5 changes data

Import an uploaded file into one object (up to 10000 rows per call; use rows.offset for more), matching on match_on (a unique field, or a list of fields forming a composite unique key). atomic=false (default) imports the valid rows and reports the rest; atomic=true imports nothing if any row fails. Each error has row (source line), identifier, field, code and message. Columns map to fields of the same name unless columns {column: field|null} says otherwise. links [{column, relationship, target_field}] link each row to the record whose unique target_field equals the column value. AgentDB never creates missing targets: on_unresolved_link decides what happens to rows whose target doesn't exist (import_unlinked: import without the link, default; skip: leave the row out; reject: import nothing); every such row is reported and summarized in unresolved_links. Use dry_run=true first: it reports exactly what would happen and writes nothing. Row-level errors name the source line. The dry run returns the same value_suggestions as imports_inspect (original, proposed value, level, certainty, rows): suggested_normalize is unambiguous only, uncertain_normalize needs review; ambiguous or unmatched values are never guessed. normalize {column: {from: to}} replaces exact cell values (only after the user agreed; never on unique/match fields, no chained rules); the report lists every transformed cell with row, original and new value. Uncertain mappings (anything beyond spacing or case against one allowed value) are refused (dry run too) with UNCERTAIN_NORMALIZE_NOT_CONFIRMED and nothing is written. Only the person decides them: pass confirm_uncertain [{column, from, to, confirm_token}] (tokens from the refusal) for the ones they approved; never on your own judgment. If you can't ask, leave them out and report them. match_fold "case" (or "trim") matches match_on values ignoring case/spacing (stored values kept; see match_key_case_variants in the dry run). One transaction per call; pass idempotency_key so a retry replays the report instead of importing twice.

MCP tool

imports_run

REST

POST /v1/workspaces/{ws}/imports/run scope records:write

Arguments

Example

file_id comes from imports_inspect (file_id of the uploaded file).

{
  "tool": "imports_run",
  "arguments": {
    "file_id": "fil_example",
    "object": "contact",
    "match_on": "email",
    "dry_run": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "imports_run",
    "arguments": {
      "file_id": "fil_example",
      "object": "contact",
      "match_on": "email",
      "dry_run": true
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/imports/run" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"fil_example","object":"contact","match_on":"email","dry_run":true}'

#imports_start

stable added in 0.2.0-alpha.5 changes data

Start a file import (CSV, JSON or JSONL) without sending the file through this tool. Returns upload_url for a one-time HTTPS PUT (curl -sS --fail-with-body -T <file> '<upload_url>') and browser_upload_url for a person when your sandbox has no internet access. The link works once, for 30 minutes, and is not an API key. Then call imports_inspect with upload_id.

MCP tool

imports_start

REST

POST /v1/workspaces/{ws}/imports scope records:write

Arguments

Example

{
  "tool": "imports_start",
  "arguments": {
    "filename": "contacts.csv",
    "format": "csv"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "imports_start",
    "arguments": {
      "filename": "contacts.csv",
      "format": "csv"
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/imports" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"contacts.csv","format":"csv"}'

#records_export

stable added in 1.0.0-rc.6 read-only

Export records, links, schema and file metadata as NDJSON (owners and admins; your permissions apply; max 2 MiB here). Larger exports and file bytes: GET /v1/workspaces/{ws}/export?format=bundle or agentdb data-export.

MCP tool

records_export

REST

GET /v1/workspaces/{ws}/export scope records:read

Arguments

Example

{
  "tool": "records_export",
  "arguments": {
    "format": "ndjson",
    "objects": [
      "contact"
    ]
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_export",
    "arguments": {
      "format": "ndjson",
      "objects": [
        "contact"
      ]
    }
  }
}

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/export" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#uploads.put

stable

Upload the file for a one-time link (no API key)

REST

PUT /v1/uploads/{token} no authentication

Example

curl -s -X PUT "https://app.agentdb.link/v1/uploads/<token>"

#workspace_import

stable added in 1.0.0-rc.8 changes data

Re-import a data export (records_export / GET /export bundle .tar.gz, or .ndjson) into a NEW workspace of your account; it never merges into an existing one. Upload the bundle first as a file of the workspace you pass (imports_start upload_url, or the REST file upload for big bundles), then pass its file_id. Records, schema ids, links, file bytes with every version are kept; files pass the file policy, scanner and quota again. Use dry_run=true first: counts, problems and quota impact, nothing created. Automations are left out unless include_automations=true; then flows, jobs and webhooks are paused (webhooks with a new secret: rotate it) and approval policies disabled. You become the owner. Pass idempotency_key: a retry returns the same workspace.

MCP tool

workspace_import

CLI

agentdb workspace import

Arguments

Example

file_id: upload the export bundle first (imports_start upload_url or the REST file upload).

{
  "tool": "workspace_import",
  "arguments": {
    "file_id": "fil_exampleexampleexampleexamp",
    "name": "Example CRM (copy)",
    "dry_run": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "workspace_import",
    "arguments": {
      "file_id": "fil_exampleexampleexampleexamp",
      "name": "Example CRM (copy)",
      "dry_run": true
    }
  }
}

agentdb workspace import [options] <bundle>