# API overview

Rowset exposes authenticated REST endpoints for account checks, dataset creation,
profile-wide row search, dataset rows, projects, schema changes, image/audio assets,
exports, and public preview settings.

## Base URL

```text
https://rowset.app/api
```

If you use a self-hosted instance, replace this value with the public URL you
expose for its REST API, including the `/api` path. For example:

```text
https://rowset.example.com/api
```

Create the API key on the same instance you connect to.

Scripts can use this URL directly. For the Rowset CLI, see
[Use Rowset from the CLI](/docs/use-cli).

## Authentication

Use your API key as a bearer token. After signing in, copy your key from Settings or from the dashboard agent prompt.

```http
Authorization: Bearer YOUR_ROWSET_API_KEY
```

For MCP clients, store the key in a private env var such as `ROWSET_API_KEY` and
set the client's bearer-token env-var field to `ROWSET_API_KEY`.

Example request:

```bash
curl -H "Authorization: Bearer YOUR_ROWSET_API_KEY" "https://rowset.app/api/user"
```

Bearer authentication is the only supported private REST authentication method.
Treat API keys like passwords: do not put them in URLs, frontend code, public
repos, shared screenshots, or logs.

## API key permissions

Agent API keys can be created with one of three permission levels:

- **Read** can inspect account details, projects, datasets, rows, and exports.
- **Read + write** can also create and update projects, datasets, rows, relationships, and public preview settings.
- **Admin** includes read/write access and can create new agent API keys through REST or MCP.

Use an admin key only for trusted automation that needs to provision other keys.

## First-run activation milestones

After composing a personalized first-project recommendation, a trusted
read/write agent can record the bounded `recommendation_emitted` milestone
immediately before returning it. After an explicit yes, record
`recommendation_accepted` before creating resources:

```http
POST /api/activation/milestones
{"milestone":"recommendation_emitted"}
```

The endpoint is idempotent and accepts only those two milestone names. Never
send recommendation text, user context, resource names, secrets, or dataset
contents. First project creation, first dataset creation, and the first verified
indexed-row update are recorded by Rowset itself.

## Interactive API docs

Rowset also exposes generated API docs from the backend schema:

[Open generated API docs](https://rowset.app/api/docs)

Use those generated docs when you want request/response schemas or to inspect lower-level endpoint details. Use this docs section for workflow-oriented guidance.

## Sections

Most users only need three docs in this reference section:

- [Dataset API](/docs/dataset-api) for creating datasets, searching rows,
  updating schema, linking datasets, attaching image or audio assets, exporting
  snapshots, and managing public previews.
- [MCP tool reference](/docs/mcp-tools) for the equivalent agent-facing tool
  groups.
- [Configure agent access](/docs/configure-agent-access) for API-key
  permissions, installable skills, and safe setup prompts.

Use the smaller endpoint pages only when you need a narrow lookup:
[User API](/docs/user-api) verifies a key and profile details, while
[Project API](/docs/project-api) covers projects and sections.

## Related docs

- [Connect over MCP](/docs/connect-mcp) for agent-native tool access.
- [Dataset API](/docs/dataset-api) for dataset and row endpoints.
- [MCP tool reference](/docs/mcp-tools) for MCP tool groups.