Source: https://datafa.st/docs/api
Markdown source: https://datafa.st/docs/api.md
Description: Learn how to authenticate and interact with the DataFast API.

# Get started with the DataFast API

Use the DataFast API to read analytics, send server-side events, and manage your DataFast account from your own backend, scripts, or AI agents.

There are two API surfaces:

| Surface | Token | Use it for |
|---|---|---|
| Website API | `df_` website API key | Read analytics, list visitors, send goals, send payments, identify users, or query one website |
| Account API | `dft_` account token | Manage websites, create API keys, create funnels, manage alerts, invite team members, connect integrations, or let an AI agent manage your account |
| CLI | `dft_` or `df_` | Run the same workflows from a terminal with `datafast` |

## Which one should I use?

- **I want to read analytics for one website:** use a `df_` key and the [analytics endpoints](/docs/api/website/analytics), [visitor endpoints](/docs/api/website/visitors), or the [API playground](/docs/api/playground).
- **I want to send events from my backend:** use a `df_` key with [goals](/docs/api/website/goals), [payments](/docs/api/website/payments), or [identify users](/docs/api/website/identity/identify).
- **I want an AI agent or script to manage my account:** use a `dft_` token with the [Account API](/docs/api/account) or the [DataFast CLI](/docs/cli-introduction).
- **I want to manage one website without full account access:** create a scoped `dft_` token with a website allowlist, or use a `df_` key for supported website-scoped admin routes. Read [authentication and scopes](/docs/api/authentication) before giving a token to an agent.

## Base URL

The base URL for all v1 endpoints is:

`https://datafa.st/api/v1/`

## Authenticate requests

All API requests use a Bearer token:

```http
Authorization: Bearer YOUR_TOKEN
```

Create website API keys in **Website settings -> API**. Create account tokens in **Account settings -> API**, or with [`datafast tokens create`](/docs/cli-tokens).

Keep both token types secret. Do not expose them in frontend code or public repositories.

## Get API keys from the dashboard

### How to get a DataFast website API key (`df_`)

Create a website API key from [Website settings -> Developer](/dashboard#website-api-key). If you are signed in, use the website selector in this docs header to switch the link to another website.

![Create a DataFast website API key](/blog-how-to-get-datafast-website-api-key.jpg.jpg)

### How to get a DataFast account API token (`dft_`)

Create an account API token from [Account settings -> API](https://datafa.st/dashboard/settings?tab=api). Use account tokens for CLI sessions, AI agents, and account automation.

![Create a DataFast account API token](/blog-how-to-get-datafast-account-api-key.jpg)

## Common use cases

- [Get analytics data](/docs/api/website/analytics)
- [List visitors](/docs/api/website/visitors)
- [Get funnel analytics](/docs/api/website/analytics/funnel-results)
- [Create a custom goal](/docs/api/website/goals)
- [Identify a user from your backend](/docs/api/website/identity/identify)
- [Manage websites, funnels, alerts, and tokens](/docs/api/account)
- [Use the CLI](/docs/cli-introduction)
- [Apps built on the API](/docs/api/apps-built-on-api)

> Try the [API playground](/docs/api/playground) to test website and account API endpoints interactively.

---

**Successful requests** return a `200 OK` status and a body like:

```json
{
  "status": "success",
  "data": { ... } // Endpoint-specific data
}
```

## Errors

Most failed requests return an appropriate HTTP status code and a JSON error body:

```json
{
  "status": "error",
  "error": {
    "code": HTTP_STATUS_CODE,
    "message": "A descriptive error message"
  }
}
```

Common error codes:

| Code | Meaning | Common causes |
|---|---|---|
| `400` | Bad request | Missing required fields, invalid JSON body, invalid query parameter, invalid date range, invalid ObjectId, invalid enum value |
| `401` | Unauthorized | Missing `Authorization` header, invalid token, wrong token prefix, expired or revoked key |
| `403` | Forbidden | Token does not have the required permission, account does not have API access, token cannot access the requested website, role does not allow the write action |
| `404` | Not found | Website, visitor, funnel, alert, API key, token, or other resource does not exist or is not accessible to the token |
| `409` | Conflict | Resource already exists, such as a duplicate website, pending invite, or duplicate funnel name |
| `429` | Rate limited | Too many requests for the same token. Check the `X-RateLimit-*` response headers |
| `500` | Server error | Unexpected server-side error |
| `504` | Timeout | A long-running delete operation timed out. Retry with a smaller time range |

Some endpoints can return endpoint-specific errors. For example, website deletion is dashboard-only and returns `403`, and `POST /api/v1/payments` returns a plain `{ "error": "..." }` body for validation errors.

Rate-limited responses include:

```json
{
  "error": "Too many requests",
  "message": "Rate limit exceeded...",
  "limit": 60,
  "remaining": 0,
  "reset": 1716249600
}
```