Schema

#indexes_create

stable added in 1.0.0-rc.6 changes data

Add a named index on a field that you filter or sort on often (max 5 per object, 20 per workspace). Renames keep it working. AgentDB tells you when one helps: records_query and records_aggregate return performance.index_recommended with suggested_arguments for this tool. Indexes help only on large objects (5,000+ records) with selective filters (eq/in/ranges, not neq or contains) or sorts. Each index adds work to every write of that object. To verify, rerun the query with explain=true and compare performance.explain.duration_ms and plan.

MCP tool

indexes_create

REST

POST /v1/workspaces/{ws}/indexes scope schema:write

CLI

agentdb indexes create

Arguments

Example

Usually the suggested_arguments of a performance.index_recommended hint (records_query, records_aggregate) or of indexes_list include_recommendations=true.

{
  "tool": "indexes_create",
  "arguments": {
    "name": "contact_status",
    "object": "contact",
    "field": "status"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "indexes_create",
    "arguments": {
      "name": "contact_status",
      "object": "contact",
      "field": "status"
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/indexes" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"contact_status","object":"contact","field":"status"}'

agentdb indexes create [options] <name> <object> <field>

#indexes_drop

stable added in 1.0.0-rc.6 changes data

Remove a named index.

MCP tool

indexes_drop

REST

DELETE /v1/workspaces/{ws}/indexes/{index} scope schema:write

CLI

agentdb indexes drop

Arguments

Example

{
  "tool": "indexes_drop",
  "arguments": {
    "index": "contact_email"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "indexes_drop",
    "arguments": {
      "index": "contact_email"
    }
  }
}

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/indexes/contact_email" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

agentdb indexes drop [options] <name>

#indexes_list

stable added in 1.0.0-rc.6 read-only

Named field indexes and the limits (5 per object, 20 per workspace). include_recommendations=true also returns index recommendations from queries run recently (ranked by total time, with evidence, can_create and the suggested indexes_create arguments). Check here before creating an index so you never add a redundant one.

MCP tool

indexes_list

REST

GET /v1/workspaces/{ws}/indexes scope schema:read

CLI

agentdb indexes list

Arguments

Example

{
  "tool": "indexes_list",
  "arguments": {
    "include_recommendations": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "indexes_list",
    "arguments": {
      "include_recommendations": true
    }
  }
}

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

agentdb indexes list [options]

#schema.object.get

stable

schema object get

REST

GET /v1/workspaces/{ws}/object-types/{object} scope schema:read

Example

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

#schema_define_field

stable added in 0.2.0-alpha.4 or earlier changes data

Add a typed field to an object type. Types: text, integer, boolean, date (YYYY-MM-DD), datetime (RFC 3339 with timezone), enum (needs enum_values), number (finite float), decimal (exact, string "12.50"; options.scale, default 2), currency ({amount: "12.50", currency: "EUR"}; options.scale, options.currencies) - use decimal/currency for money, time (HH:MM[:SS]), timezone (IANA name), duration (whole seconds or ISO 8601 like PT1H30M), multi_select (array of strings; enum_values optional), list (options.item_type), json (object, max 32 KB, depth 8), email, url (http/https), phone (E.164 like +31201234567), address ({line1,line2,line3,city,region,postal_code,country}), geo ({lat, lon}), rich_text (Markdown without HTML), formula (computed: options.expression like "price * quantity", options.result_type number|text|boolean), status (enum_values + options.transitions {from: [to...]}, options.initial), user_ref (a person's account id acc_…), agent_ref (an agent id agt_…), file (file id fil_…; options.multiple for a list; query has/is_null). See docs/FIELD-TYPES.md. unique=true makes it usable as an upsert match key. required=true is only allowed while the object has no records. To change or remove a field later use schema_update_field / schema_remove_field.

MCP tool

schema_define_field

REST

POST /v1/workspaces/{ws}/object-types/{object}/fields scope schema:write

Arguments

Example

{
  "tool": "schema_define_field",
  "arguments": {
    "object": "contact",
    "name": "email",
    "type": "text",
    "unique": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_define_field",
    "arguments": {
      "object": "contact",
      "name": "email",
      "type": "text",
      "unique": true
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types/contact/fields" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"email","type":"text","unique":true}'

#schema_define_object

stable added in 0.2.0-alpha.4 or earlier changes data

Create a new object type (e.g. 'contact'). Names are lowercase snake_case. Fails with ALREADY_EXISTS if it exists.

MCP tool

schema_define_object

REST

POST /v1/workspaces/{ws}/object-types scope schema:write

Arguments

Example

{
  "tool": "schema_define_object",
  "arguments": {
    "name": "contact",
    "description": "People we talk to"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_define_object",
    "arguments": {
      "name": "contact",
      "description": "People we talk to"
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"contact","description":"People we talk to"}'

#schema_define_relationship

stable added in 0.2.0-alpha.4 or earlier changes data

Create a directed relationship type from source_object to target_object (e.g. contact.works_at -> company). cardinality 'one' allows one target per source record.

MCP tool

schema_define_relationship

REST

POST /v1/workspaces/{ws}/relationship-types scope schema:write

Arguments

Example

{
  "tool": "schema_define_relationship",
  "arguments": {
    "name": "works_at",
    "source_object": "contact",
    "target_object": "company",
    "cardinality": "one"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_define_relationship",
    "arguments": {
      "name": "works_at",
      "source_object": "contact",
      "target_object": "company",
      "cardinality": "one"
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/relationship-types" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"works_at","source_object":"contact","target_object":"company","cardinality":"one"}'

#schema_define_unique_key

stable added in 0.2.0-alpha.8 changes data

Declare 2-5 fields that together identify one record (e.g. first_name + last_name + company). Then use them as match_on in records_upsert_batch and imports_run. Fails with SCHEMA_CONFLICT listing duplicates if existing records already share a combination. Records missing any of the fields are not constrained.

MCP tool

schema_define_unique_key

REST

POST /v1/workspaces/{ws}/object-types/{object}/unique-keys scope schema:write

Arguments

Example

{
  "tool": "schema_define_unique_key",
  "arguments": {
    "object": "contact",
    "fields": [
      "first_name",
      "last_name"
    ]
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_define_unique_key",
    "arguments": {
      "object": "contact",
      "fields": [
        "first_name",
        "last_name"
      ]
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types/contact/unique-keys" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields":["first_name","last_name"]}'

#schema_docs

stable added in 1.0.0-rc.6 read-only

Generated API documentation for THIS workspace, for building an app on it: an OpenAPI fragment with a JSON Schema per object, example create/query/upsert bodies and markdown. Only shows what you may see.

MCP tool

schema_docs

REST

GET /v1/workspaces/{ws}/docs scope schema:read

Arguments

Example

{
  "tool": "schema_docs",
  "arguments": {
    "object": "contact"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_docs",
    "arguments": {
      "object": "contact"
    }
  }
}

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

#schema_history

stable added in 1.0.0-beta.3 read-only

Schema change history, newest first: each change with the definition before and after, who made it, when, whether it can be undone and how many values were archived. Filter by object (and field). Use it to see earlier definitions or to find the change_id for schema_undo.

MCP tool

schema_history

REST

GET /v1/workspaces/{ws}/schema/history scope schema:read

CLI

agentdb schema history

Arguments

Example

{
  "tool": "schema_history",
  "arguments": {
    "object": "contact",
    "limit": 10
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_history",
    "arguments": {
      "object": "contact",
      "limit": 10
    }
  }
}

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

agentdb schema history [options]

#schema_inspect

stable added in 0.2.0-alpha.4 or earlier read-only

List every object type with its typed fields (name, type, required, unique, enum values) and relationship types. Call this first.

MCP tool

schema_inspect

REST

GET /v1/workspaces/{ws}/object-types scope schema:read

REST

GET /v1/workspaces/{ws}/schema scope schema:read

CLI

agentdb schema inspect

Arguments

Example

{
  "tool": "schema_inspect",
  "arguments": {}
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_inspect",
    "arguments": {}
  }
}

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

agentdb schema inspect [options]

#schema_object_rules

stable added in 1.0.0-rc.8 read-only

Record rules of one object: append_only (stored records can't be updated, deleted, merged or archived except by an owner; APPEND_ONLY) and completion_rules (a field may move to some values only while every linked record is in given values; BLOCKED_BY_DEPENDENCY). Packages such as AgentTodos set them.

MCP tool

schema_object_rules

REST

GET /v1/workspaces/{ws}/object-types/{object}/rules scope schema:read

Arguments

Example

{
  "tool": "schema_object_rules",
  "arguments": {
    "object": "deal"
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_object_rules",
    "arguments": {
      "object": "deal"
    }
  }
}

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

#schema_object_rules_set

stable added in 1.0.0-rc.8 changes data

Set the record rules of one object (owners only). append_only true/false; completion_rules replaces the list ([] or null removes it). Omitted keys keep their value. Rules are checked against the schema first and apply to every later write (REST, MCP, CLI, imports). Audited as schema.object.rules.

MCP tool

schema_object_rules_set

REST

POST /v1/workspaces/{ws}/object-types/{object}/rules scope schema:write

Arguments

Example

{
  "tool": "schema_object_rules_set",
  "arguments": {
    "object": "audit_entry",
    "append_only": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_object_rules_set",
    "arguments": {
      "object": "audit_entry",
      "append_only": true
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types/audit_entry/rules" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"append_only":true}'

#schema_remove_field

stable added in 0.2.0-alpha.8 changes data destructive

Remove a field and its value from every record. dry_run=true shows how many values would be removed; the real removal needs confirm=true. Fields in a unique key must have the key removed first. The values are archived (see values_kept_until); schema_undo with the returned change_id restores the field and its values.

MCP tool

schema_remove_field

REST

DELETE /v1/workspaces/{ws}/object-types/{object}/fields/{field} scope schema:write

Arguments

Example

{
  "tool": "schema_remove_field",
  "arguments": {
    "object": "contact",
    "field": "fax",
    "dry_run": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_remove_field",
    "arguments": {
      "object": "contact",
      "field": "fax",
      "dry_run": true
    }
  }
}

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types/contact/fields/fax" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dry_run":true}'

#schema_remove_unique_key

stable added in 0.2.0-alpha.8 changes data destructive

Remove a composite unique key (by its fields). Records are not changed.

MCP tool

schema_remove_unique_key

REST

DELETE /v1/workspaces/{ws}/object-types/{object}/unique-keys scope schema:write

Arguments

Example

{
  "tool": "schema_remove_unique_key",
  "arguments": {
    "object": "contact",
    "fields": [
      "first_name",
      "last_name"
    ]
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_remove_unique_key",
    "arguments": {
      "object": "contact",
      "fields": [
        "first_name",
        "last_name"
      ]
    }
  }
}

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types/contact/unique-keys" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields":["first_name","last_name"]}'

#schema_undo

stable added in 1.0.0-beta.3 changes data destructive

Reverse one schema change: restore a field's previous definition and its archived original values (rename, retype, enum/required/unique changes), bring back a removed field with its values, remove a field that was added, or re-add/remove a unique key. Validates every record first and changes nothing on conflict; dry_run=true previews; confirm=true is needed when the undo removes values or can't restore everything. Only the latest state can be undone: later changes to the same field must be undone first (newest first). The undo is itself a change you can undo.

MCP tool

schema_undo

REST

POST /v1/workspaces/{ws}/schema/changes/{change}/undo scope schema:write

CLI

agentdb schema undo

Arguments

Example

change_id comes from schema_history.

{
  "tool": "schema_undo",
  "arguments": {
    "change_id": "sch_example",
    "dry_run": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_undo",
    "arguments": {
      "change_id": "sch_example",
      "dry_run": true
    }
  }
}

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/schema/changes/sch_example/undo" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dry_run":true}'

agentdb schema undo [options] <change_id>

#schema_update_field

stable added in 0.2.0-alpha.8 changes data

Rename a field (rename_to; values move with it), change its type (every existing value must convert, e.g. text->integer only if all values are whole numbers; any type -> text always works), or change enum_values, required, unique or description. Validates all records first and changes nothing on failure (SCHEMA_CONFLICT with examples). options replaces the type-specific settings (e.g. decimal scale, status transitions, formula expression). dry_run=true previews affected records. Lossy conversions (datetime->date) need confirm=true. Record ids and versions stay the same.

MCP tool

schema_update_field

REST

PATCH /v1/workspaces/{ws}/object-types/{object}/fields/{field} scope schema:write

Arguments

Example

{
  "tool": "schema_update_field",
  "arguments": {
    "object": "contact",
    "field": "email",
    "rename_to": "work_email",
    "dry_run": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_update_field",
    "arguments": {
      "object": "contact",
      "field": "email",
      "rename_to": "work_email",
      "dry_run": true
    }
  }
}

curl -s -X PATCH "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types/contact/fields/email" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rename_to":"work_email","dry_run":true}'

#schema_update_relationship

stable added in 1.0.0-rc.6 changes data

Make a relationship required (every source record must be linked) or optional, or change its description. Making it required is refused while records lack the link; dry_run=true lists them. AgentDB never creates targets.

MCP tool

schema_update_relationship

REST

PATCH /v1/workspaces/{ws}/relationship-types/{object}/{relationship} scope schema:write

Arguments

Example

{
  "tool": "schema_update_relationship",
  "arguments": {
    "object": "contact",
    "relationship": "works_at",
    "required": false,
    "dry_run": true
  }
}

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "schema_update_relationship",
    "arguments": {
      "object": "contact",
      "relationship": "works_at",
      "required": false,
      "dry_run": true
    }
  }
}

curl -s -X PATCH "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/relationship-types/contact/works_at" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"required":false,"dry_run":true}'