Languages overview

AgentDB has one REST API. Any language that can send HTTPS requests can use it. You need no SDK: each guide uses the language's own HTTP client.

Every guide covers the same topics, in the same order:

Connect: base URL, environment variables and the Authorization header.
Read records.
Create and update records, with version checks.
Query with filters, sorting and cursor pages.
Link records and list the links.
Upload, download and share files.
Handle errors.
Rate limits and retries.
Idempotency keys for safe retries.

All code on these pages runs on a server. Never put the key in browser code. See Security for apps.

#Tested examples

The code blocks on each guide are not copies. The docs include them from one runnable program per language. npm run docs:examples starts a local AgentDB, creates the schema below and runs every program. Each program must print one OK line per topic.

Language	Guide	HTTP client	Tested
JavaScript	JavaScript	`fetch` (Node.js 22)	Locally and in CI
TypeScript	TypeScript	`fetch` (Node.js 22)	Locally and in CI
PHP	PHP	curl extension	Locally and in CI
Python	Python	`urllib` (standard library)	Locally and in CI
Go	Go	`net/http`	In CI
C#	C#	`HttpClient`	Locally and in CI
Java	Java	`java.net.http.HttpClient`	In CI
Ruby	Ruby	`Net::HTTP`	Locally and in CI
Rust	Rust	`reqwest`	In CI
Swift	Swift	`URLSession`	Locally (macOS); in CI when the runner has Swift
Kotlin	Kotlin	`java.net.http.HttpClient`	In CI when the runner has Kotlin

AI tools can read the same list as JSON: examples.json.

#Environment variables

Every example reads three variables:

Variable	Value
`AGENTDB_URL`	`https://app.agentdb.link` (the default)
`AGENTDB_API_KEY`	A server-side key, best an agent key
`AGENTDB_WORKSPACE`	The workspace id, `ws_...`

Set them in your server's secret settings, or in a .env file that is not in Git.

#The example schema

The examples use two objects and one relationship: a contact with a name, an e-mail address and a score, a company with a name, and works_at from a contact to its company. Ask your AI to create them, or run these calls once with an admin or owner key.

RESTChecked

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

RESTChecked

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

RESTChecked

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

RESTChecked

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

RESTChecked

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/object-types" \
  -H "Authorization: Bearer $AGENTDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "company"}'

RESTChecked

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

RESTChecked

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

cardinality: "one" means a contact works at one company. A company can have many contacts.

#The API in one table

All paths start with https://app.agentdb.link/v1/workspaces/{ws}. Every answer is JSON: {"data": ...} on success, {"error": {...}} on failure.

Task	Call
Inspect the schema	`GET /object-types`
Create a record	`POST /records` with `{"object", "data"}`
Read a record	`GET /records/{id}`
Update a record	`PATCH /records/{id}` with `{"version", "data"}`
Query	`POST /query` with `{"object", "where", "sort", "limit", "cursor"}`
Link two records	`POST /links` with `{"relationship", "source_record_id", "target_record_id"}`
List linked records	`GET /records/{id}/related?relationship=<name>`
Announce a file	`POST /files` with `{"filename", "content_type", "size"}`
Upload its bytes	`PUT /files/{id}/content` with `Content-Type: application/octet-stream`
Attach it to a record	`POST /attachments` with `{"file_id", "record_id"}`
Download it	`GET /files/{id}/content`
Signed link for a browser	`POST /files/{id}/links` with `{"expires_in_seconds"}`
Changes since a point	`GET /changes?after=<seq>&wait=1`

The reference lists every operation with its arguments. The error codes page explains each error.

#Errors, rate limits and retries

Errors come as {"request_id", "error": {"code", "message", "retryable", "details"}} with an HTTP status. Act on code, not on the message text.
VERSION_CONFLICT (409): someone changed the record after you read it. Read it again, apply your change, and send the new version.
RATE_LIMITED (429): wait for the seconds in the Retry-After header, then retry. Without the header, back off: 0.5, 1, 2, 4 seconds.
Network errors and timeouts: retry a read freely. Retry a write only with the same Idempotency-Key. AgentDB then returns the first result and writes nothing twice. Keys are kept for 7 days.