Concepts

This page explains the words the rest of the documentation uses. After reading it, you can design your own data model. You will also know how AgentDB keeps your data safe from double writes and lost updates.

#Workspaces

A workspace is one isolated project. It has its own objects, records, files and settings. Nothing in one workspace can see another workspace.

• Id: starts with ws_ and never changes.
• Name: a readable name that you can change.
• Slug: a short handle such as example-crm. It is unique in your account.
• Default workspace: your first workspace. Calls that name no workspace use it.

An account can have several workspaces. Create one in the app, with agentdb workspace create "Example CRM", or ask your agent.

There are two kinds of API key. An account key reaches every workspace of your account. A workspace key reaches exactly one workspace. A key that asks for a workspace it cannot reach gets NOT_FOUND.

#Objects and fields

An object is a type of record, like a table in a spreadsheet. Examples are contact, company and invoice.

A field is one typed value on an object, like a column. Every field has a name and a type. AgentDB checks each value against its type on every write.

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

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

{"tool": "schema_define_field", "arguments": {"object": "contact", "name": "stage", "type": "enum", "enum_values": ["lead", "customer"]}}

AgentDB has more than 25 field types. Common ones are text, integer, boolean, date, datetime, enum, decimal, currency, email and file. Each type is described in Field types.

Some field options matter often:

• unique: no two records may have the same value. A unique field can identify a record during bulk upserts.
• required: every record must have a value. You can add a required field only while the object has no records.
• enum_values: the allowed values of an enum, status or multi_select field.

You can change the schema later. Rename or retype a field, or remove it. Each change can run as a dry run first. AgentDB keeps a schema history, and you can undo a change. Removed fields come back with their values.

See the whole schema at any time:

agentdb schema inspect

#Relationships

A relationship is a named link type between two objects. For example, a contact works_at a company.

• The source object is where the link starts: contact.
• The target object is where it points: company.
• The cardinality is one or many. With one, each contact links to at most one company.

{"tool": "schema_define_object", "arguments": {"name": "company"}}

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

You can follow a link in both directions. Outgoing goes from contact to company. Incoming goes from company to its contacts.

#Records

A record is one row of an object, such as one contact. Every record has:

• an id that starts with rec_,
• the object it belongs to,
• its field values under data,
• a version number,
• created_at and updated_at times.

{"tool": "records_create", "arguments": {"object": "contact", "data": {"email": "ada@example.com", "stage": "lead"}}}

A field without a value and a field set to null mean the same thing. Setting a field to null in an update removes its value.

Deleting a record also removes its links and attachments. The record goes to the recycle bin first. You can restore it there for 30 days by default.

#Versions

Every record starts at version 1. Each change adds one. An update must name the version you last read:

{"tool": "records_update", "arguments": {"record_id": "$ADA", "version": 1, "data": {"stage": "customer"}}}

Did someone else change the record after you read it? Then your update fails with VERSION_CONFLICT, and nothing is written. Read the record again, apply your change and try again. This way no update silently overwrites another.

{"tool": "records_update", "arguments": {"record_id": "$ADA", "version": 1, "data": {"stage": "lead"}}}

#Idempotency keys

A network error can leave you unsure whether a write happened. An idempotency key makes a retry safe.

1. Send the write with a key you choose, such as create-ada-2.
2. If you are unsure it worked, send the same write with the same key again.
3. AgentDB returns the original result and writes nothing twice.

curl -X POST https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-bob-1" \
  -d '{"object":"contact","data":{"email":"bob@example.com"}}'

curl -X POST https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-bob-1" \
  -d '{"object":"contact","data":{"email":"bob@example.com"}}'

The second call returns the same record. The response header Idempotent-Replayed: true tells you it was a replay.

Some rules:

• Use a new key for each new intention.
• The same key with a different request fails with IDEMPOTENCY_KEY_REUSED.
• A request that failed stored nothing. Fix it and retry with the same key.
• AgentDB keeps keys for 7 days, per workspace.

MCP tools take an idempotency_key argument. CLI commands take -k or --idempotency-key.

#Next steps

• Query your data with filters, sorting and totals.
• Files and imports to bring in existing data.