# How to connect an AI agent to the Rowset Dataset API

A practical setup guide for giving a trusted AI agent private REST access to Rowset datasets without leaking keys or losing row context.

To connect an AI agent to the Rowset Dataset API, create or copy a scoped
agent API key, store it in the agent runtime as a private secret, send it as
`Authorization: Bearer <key>`, then have the agent inspect the dataset before
it creates or updates rows. The setup is small, but the order matters.

The goal is not to give the agent "API access" in the abstract. The goal is to
give a trusted agent a private row backend with enough schema, identity, and
instructions to act without guessing.

Use REST when the agent runtime can make HTTP requests but cannot configure MCP,
or when a backend job, script, or integration should call Rowset directly. Use
[Rowset MCP](/docs/connect-mcp) when the client can discover tools and schemas
through a connected MCP server.

## Quick setup checklist

| Step | What to do | Why it matters |
|---|---|---|
| 1 | Create or copy an agent API key in Rowset | The key defines what the trusted client can do |
| 2 | Store the key as `ROWSET_API_KEY` or another private secret | Bearer tokens give access to whoever holds them |
| 3 | Set the REST base URL from the Rowset dashboard or docs | The agent needs one stable API origin |
| 4 | Send `Authorization: Bearer <key>` on private requests | This matches standard bearer-token API practice |
| 5 | Find or create the dataset | The agent needs the dataset key before row work |
| 6 | Inspect the dataset before edits | Headers, index column, instructions, and schema prevent bad writes |
| 7 | Use index-based row operations when possible | Stable business keys are safer than fuzzy row matching |
| 8 | Keep public previews read-only | Sharing a browser view is not the same as granting API access |

If you are starting from zero, first read
[What is an agent-managed dataset?](/blog/agent-managed-datasets). This guide is
the REST setup version of that concept.

## 1. Choose REST only when it is the right interface

Rowset gives agents two private programmatic paths:

- **MCP** for compatible agent clients that can discover Rowset tools and call
  them directly.
- **REST** for scripts, backend jobs, constrained runtimes, or agents that can
  make HTTP requests but do not have a usable MCP client.

The Model Context Protocol specification defines a standard way for applications
to connect language models with tools and data sources. For HTTP-based MCP
authorization, the current
[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
requires clients to send access tokens in the
`Authorization: Bearer <access-token>` header on requests to the server.

REST uses the same bearer-header shape in Rowset, but the interaction model is
different. With MCP, the agent discovers tools. With REST, you must give the
agent the API base URL, the relevant endpoint paths, and the workflow rules it
should follow.

Use this rule:

- If the agent can use MCP, start with [Connect over MCP](/docs/connect-mcp).
- If the agent can only make HTTP calls, use the Dataset API.
- If the workflow is a scheduled script or backend worker, REST is usually the
  clearer path.

For the fuller protocol decision, read
[When should an AI agent use MCP instead of REST?](/blog/mcp-vs-rest-ai-agents).

## 2. Create the smallest useful key

Start in Rowset's agent access flow and choose the permission level that matches
the job:

- **Read** for inspection, reporting, and exports.
- **Read + write** for agents that create or update datasets, rows, projects,
  relationships, or preview settings.
- **Admin** only when the agent must create other agent API keys.

Do not use a broad key because it is convenient.
[OWASP's API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/)
continues to treat broken authentication as a major API risk, and bearer tokens
are intentionally simple: whoever has the token can use it until it is revoked
or expires according to the system's rules.

That simplicity is useful for trusted agents, but it changes how you should
handle prompts. Do not paste the raw key into public issue trackers, shared
screenshots, model transcripts, or repository files. Store it in the agent
runtime's private environment or secret store.

For local or hosted agents, use a variable name such as:

```bash
ROWSET_API_KEY=...
```

Then instruct the agent to send:

```http
Authorization: Bearer ${ROWSET_API_KEY}
```

Swagger's
[OpenAPI bearer authentication documentation](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/)
describes bearer authentication as an HTTP authentication scheme where the
client sends the bearer token in the `Authorization` header. Rowset's REST path
follows that convention.

## 3. Give the agent the minimum setup prompt

A good REST setup prompt should be short and operational. It should not contain
private data beyond the secret reference.

Use a prompt like this:

```text
Use Rowset as the private dataset backend for this workflow.

REST API base: https://rowset.lvtd.dev/api
Authentication: send Authorization: Bearer from the private ROWSET_API_KEY env var.

Before changing rows:
1. Find or create the correct dataset.
2. Inspect the dataset detail.
3. Read headers, index_column, column schema, instructions, and metadata.
4. Use by-index row lookup/update when the dataset has a stable business key.
5. Ask before deleting rows, archiving datasets, or changing public preview settings.
```

That gives the agent a stable operating contract without exposing the key itself.

If your agent also supports reading URLs, include these public references:

- [Dataset API](/docs/dataset-api)
- [Configure agent access](/docs/configure-agent-access)
- [Help agents discover Rowset](/docs/agent-discovery)
- [MCP tool reference](/docs/mcp-tools)

The agent should use the docs for current endpoint shapes and your prompt for
workflow intent.

## 4. Find or create the dataset

The agent needs a dataset key before it can do row work.

If the dataset already exists, the agent should search or list datasets, then
inspect the one it plans to use. If the workflow is new, have the agent create a
small dataset with clear headers, a useful description, persistent instructions,
and an explicit `index_column` when a durable business key exists.

For a customer list, the index might be `email`. For a catalog, it might be
`sku`. For a content queue, it might be `slug`. If no natural key exists,
Rowset can generate `rowset_id` so updates still have a stable target.

This is the first place many agent workflows fail. A vague dataset like
`items` with headers like `name`, `status`, and `notes` may be readable to a
human, but an agent needs more context. Add column descriptions, choice values,
dataset instructions, and metadata when those rules affect future writes.

Useful companion guides:

- [How to choose an index column for agent-managed rows](/blog/choose-index-column-agent-rows)
- [Rowset rowset_id vs business keys](/blog/rowset-id-vs-business-keys)
- [How to structure dataset instructions for AI agents](/blog/structure-dataset-instructions-ai-agents)
- [Designing schema for agents](/docs/design-schema)

## 5. Inspect before every meaningful write

Before the agent creates, patches, or deletes rows, make it inspect the dataset.

The dataset detail response is the control plane for the workflow. It tells the
agent:

- which headers exist,
- which column is the index column,
- what semantic column schema exists,
- what dataset instructions and metadata apply,
- which project or section owns the dataset,
- and which relationships may affect row values.

That context is more important than a clever prompt. If the dataset says
`status` must be one of `Ready`, `Doing`, or `Done`, the agent should not invent
`In progress`. If the instructions say "never mark a request done without a PR
link," that rule should guide the patch body.

Treat dataset inspection as the REST equivalent of loading tool schemas in MCP:
it is the step that turns raw API calls into controlled row operations.

## 6. Use by-index operations for durable row updates

When the dataset has a stable index, prefer by-index operations for lookup and
update. If the agent may retry after timeouts, follow the
[idempotent update contract](/blog/idempotent-ai-agent-updates): identify the
row by index, patch absolute values, and read the row before replaying an
uncertain write.

That means the agent can say "update `sku=ADAPTER-001`" or "patch
`email=ada@example.com`" instead of searching a list response for a row that
looks close. This reduces duplicate rows and wrong-row updates.

A good row update prompt is specific:

```text
Update the product catalog row where sku is ADAPTER-001.
Set status to active and price to 19.99.
Do not change any other fields.
```

A risky row update prompt is vague:

```text
Update the adapter row.
```

The second version forces the agent to guess. If there are two adapters, or if
one row is named "USB-C Adapter" and another is named "Travel Adapter," the
workflow becomes fragile.

## 7. Keep review separate from mutation

Public previews are useful when humans need to inspect a dataset in the browser,
but they are not an authentication layer and they are not a replacement for REST
or MCP access.

Use this split:

- Agent writes through private REST or MCP access.
- Human reviews through the dashboard, exports, or optional read-only previews.
- Sensitive changes stay behind scoped API keys.

That split keeps the agent's mutation path private while still giving humans a
clean way to review the result.

For example, a feedback triage workflow can let an agent classify requests,
attach source URLs, and update statuses through the Dataset API. A product
manager can review a read-only preview afterward without giving that preview
write access.

## Common setup mistakes

### Pasting the key into the task prompt

Reference the secret variable instead. The agent should know that
`ROWSET_API_KEY` exists, not the key value.

### Creating a dataset without an index strategy

If a durable business key exists, set it. If not, use Rowset's generated
`rowset_id`. Do not rely on row order as identity.

### Skipping dataset inspection

An agent that skips inspection is likely to miss instructions, choice values,
relationships, or schema changes.

### Treating public previews as access control

Public previews are read-only sharing surfaces. Private mutation belongs in REST
or MCP with scoped authentication.

### Asking the agent to "sync everything"

Give bounded actions: find the dataset, inspect it, patch specific rows, report
what changed. Broad sync prompts are harder to verify and easier to overreach.

## A practical first run

For a first production-ish test, use a small dataset and a bounded task.

1. Create a dataset named `Agent QA checklist`.
2. Use headers: `check_id`, `area`, `status`, `owner`, `source_url`, `notes`.
3. Set `check_id` as the index column.
4. Add instructions: "Only use status values Ready, Checking, Blocked, Done.
   Never mark Done without a source_url."
5. Ask the agent to create three rows.
6. Ask the agent to inspect the dataset.
7. Ask it to update one row by `check_id`.
8. Review the changed rows in Rowset.

That test covers the real workflow surface: authentication, dataset context,
stable row identity, create, inspect, update, and human review.

## FAQ

### Should my agent use MCP or REST for Rowset?

Use MCP when the client can configure Rowset's hosted MCP server and benefit
from tool discovery. Use REST when the agent can make HTTP requests but cannot
configure MCP, or when a script or backend job needs a plain API surface.

### Where should I store the Rowset API key?

Store it in the agent runtime's private environment or secret manager. A common
name is `ROWSET_API_KEY`. Do not paste the raw value into public prompts,
repositories, screenshots, or issue trackers.

### What should the agent do before updating rows?

It should inspect the dataset, read the headers, index column, semantic schema,
instructions, and metadata, then use by-index row operations when a stable index
exists.

### Can I share a Rowset dataset publicly for review?

Yes, use a public preview when the data is safe to share. Public previews are
read-only browser views. They do not replace private REST or MCP authentication
for agent writes.