---
title: "API Overview - Documentation"
description: "Introduction to the AI for Database REST API. Base URLs, versioning, rate limits, and response formats."
canonical: "https://www.aifordatabase.com/docs/api-overview/"
---

# API Overview

intermediate 5 min read

## API Overview

The AI for Database REST API lets applications and AI agents integrate natural-language querying, raw database results, dashboards, complete workflow automation, webhook subscriptions, usage, and API-key management. An agent can inspect sanitized connection metadata and schema, run raw SQL, create an encrypted outbound credential, build and revise a paused workflow draft, preview its query results without delivery, test one real action, inspect sanitized delivery attempts, and explicitly publish the workflow without using the browser UI.

### Base URL

```
https://app.aifordatabase.com/api/v1
```

For self-hosted deployments, the base URL is your instance's address followed by `/api/v1`.

### Live API Reference

An interactive, always-current API reference is served by the app itself:

*   **Browsable docs:** [app.aifordatabase.com/api/v1/docs](https://app.aifordatabase.com/api/v1/docs)
*   **OpenAPI 3.1 spec:** [app.aifordatabase.com/api/v1/openapi.json](https://app.aifordatabase.com/api/v1/openapi.json)

If anything on this page ever disagrees with the OpenAPI spec, the spec wins. AI agents integrating with the API should fetch the OpenAPI spec directly.

### Versioning

The API is versioned using URL path prefixes (`/v1`). We guarantee backward compatibility within a major version. Breaking changes will be released under a new version prefix with a migration guide.

### Authentication

AI calls use the same managed AI and persistent credit balance as the app. Paid usage requires a positive balance; credits do not reset monthly.

All API requests require authentication via a Bearer token in the Authorization header. API keys start with `afd_`:

```bash
curl -H "Authorization: Bearer afd_your_api_key" \
  https://app.aifordatabase.com/api/v1/connections
```

Generate API keys in **Settings > API Keys**. Each key is scoped to specific permission areas (see [Authentication](https://www.aifordatabase.com/docs/authentication/)) and has an optional expiration date.

### Response Format

All responses are JSON with a consistent envelope — `data` and `error` are mutually exclusive:

```json
{
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "8d6eb159-9896-4274-94c7-fab3f95ae1c6",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}
```

Error responses:

```json
{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "details": { ... }
  },
  "meta": {
    "requestId": "8d6eb159-9896-4274-94c7-fab3f95ae1c6",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}
```

### Rate Limits

Limits are applied per organization, per minute:

| Plan | General requests/min | Chat requests/min |
| --- | --- | --- |
| Free | 60 | 20 |
| Pro / Max | 300 | 100 |
| Enterprise | 1,000 | 500 |

Exceeding a limit returns HTTP 429 with a `RATE_LIMITED` error code.

### Pagination

List endpoints support page-based pagination:

```bash
GET /api/v1/connections?page=1&pageSize=20
```

The response `meta.pagination` object contains `total`, `page`, `pageSize`, and `totalPages`.

Source: https://www.aifordatabase.com/docs/api-overview/