> For the complete documentation index, see [llms.txt](https://docs.csvgetter.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.csvgetter.com/api-reference.md).

# API Reference

### Authentication

CSV Getter uses two authentication mechanisms depending on the context:

#### 1. Endpoint Auth (Bearer Token)

For endpoints with authentication enabled, include the token you set in the dashboard:

```
Authorization: Bearer your-endpoint-token
```

This protects individual endpoint URLs from unauthorized access.

#### 2. API Key

For programmatic endpoint creation (via `POST /urls/create`), use your API key. Find it in your dashboard under account settings.

```
Authorization: Bearer your-api-key
```

***

### Endpoints

#### `GET /` — Health Check

Returns server status.

**Request:**

```bash
curl https://api.csvgetter.com/
```

**Response (200):**

```json
{
  "status": "up",
  "message": "Server is running",
  "version": "11.0.0"
}
```

***

#### `GET /<endpoint_id>` — Fetch Export Data

The primary endpoint. Returns your data in the configured (or overridden) format.

**Request:**

```bash
curl https://api.csvgetter.com/abc123def456
```

**With URL parameters:**

```bash
curl "https://api.csvgetter.com/abc123def456?type=json_records&sql=SELECT%20*%20FROM%20csvgetter%20LIMIT%2010"
```

**With Bearer auth (if enabled on the endpoint):**

```bash
curl -H "Authorization: Bearer my-secret-token" \
  https://api.csvgetter.com/abc123def456
```

**Response varies by format.** Default is CSV:

```
name,email,status
Jane Smith,jane@example.com,Active
John Doe,john@example.com,Pending
```

JSON example (`?type=json_records`):

```json
[
  {"name": "Jane Smith", "email": "jane@example.com", "status": "Active"},
  {"name": "John Doe", "email": "john@example.com", "status": "Pending"}
]
```

**Supported URL parameters:** See URL Parameters.

***

#### `GET /files/<endpoint_id>` — Fetch Export Data (Alternate Path)

Identical behavior to `GET /<endpoint_id>`. Provided for backward compatibility.

***

#### `GET /proxy/<proxy_id>` — Proxy Endpoint

Accesses an endpoint through a proxy configuration. Useful for advanced routing setups.

**Request:**

```bash
curl https://api.csvgetter.com/proxy/xyz789
```

**Error Responses:**

| Status | Message                         |
| ------ | ------------------------------- |
| 404    | `URL not found in database.`    |
| 401    | Auth-related errors (see below) |

***

### URL Parameters Reference

All `GET` export endpoints support these query parameters:

| Parameter               | Type   | Description                                                        |
| ----------------------- | ------ | ------------------------------------------------------------------ |
| `type`                  | string | Output format override (`json_records`, `xml`, `html_table`, etc.) |
| `sql`                   | string | SQL query to filter/transform data                                 |
| `nest_json`             | string | Wrap JSON output in a named key                                    |
| `filename_timestamp`    | string | Add timestamp to filename (`true`/`end`/`start`)                   |
| `extract_json_property` | string | Extract a specific property from linked records                    |
| `all_fields`            | string | Include all fields (`true`) — requires custom parameter setup      |
| `show_wait_page`        | string | Show a loading page before redirecting (`true`)                    |
| `save_to_gdrive`        | string | Save output to Google Drive (`true`)                               |
| `save_to_gsheets`       | string | Save output to Google Sheets (`true`)                              |

***

### Response Formats

#### CSV (Default)

```
Content-Type: text/csv
Content-Disposition: attachment; filename=My_Export.csv
```

#### JSON (all json\_\* types)

```
Content-Type: text/json
```

#### XML

```
Content-Type: application/xml
```

#### HTML (html\_table, dynamic\_table, excel\_web\_query)

```
Content-Type: text/html
```

***

### Error Codes

All errors return a JSON body with an `error` or `message` field:

| Status | Error                                                     | Cause                                                       |
| ------ | --------------------------------------------------------- | ----------------------------------------------------------- |
| 400    | `Could not validate sql.`                                 | Invalid SQL query syntax                                    |
| 400    | `Custom parameter 'X' is not enabled for this object.`    | Using a custom parameter not enabled for this endpoint      |
| 401    | `Authorization header is required`                        | Auth-enabled endpoint, no header provided                   |
| 401    | `Invalid Authorization header format`                     | Header doesn't start with `Bearer`                          |
| 401    | `Invalid Authorization header`                            | Wrong Bearer token                                          |
| 401    | `AUTH_HEADER_MISSING`                                     | Missing auth header (proxy route)                           |
| 401    | `INVALID_AUTH_HEADER`                                     | Wrong auth header (proxy route)                             |
| 403    | `Not enough credits. Login at csvgetter.com to purchase.` | Credit balance is zero                                      |
| 403    | `User ID not found`                                       | User account issue                                          |
| 403    | `USER_BLOCKED`                                            | Account has been blocked                                    |
| 404    | `Object not found`                                        | Endpoint ID doesn't exist                                   |
| 404    | `URL not found in database.`                              | Proxy ID doesn't exist                                      |
| 409    | `...Airtable data structure may have changed...`          | Airtable field structure changed since endpoint was created |
| 423    | `Failed to authenticate with export platform.`            | Airtable/Notion token expired or revoked                    |
| 429    | *(varies)*                                                | Airtable's own API rate limit exceeded                      |
| 500    | `Dataframe could not be retrieved`                        | Server error fetching data                                  |

***

### Rate Guidance

CSV Getter does not impose its own rate limits, but:

* **Airtable** limits API requests to 5 requests per second per base. If your endpoint hits this, you'll get a 429 error.
* **Notion** has its own rate limits.
* Each successful, non-sample export uses 1 credit.

For high-frequency use cases, consider caching the response on your end or using scheduled jobs instead.

***

### Code Examples

#### JavaScript (Node.js / Browser)

```javascript
const response = await fetch("https://api.csvgetter.com/abc123?type=json_records", {
  headers: {
    "Authorization": "Bearer my-secret-token"  // only if auth is enabled
  }
});
const data = await response.json();
console.log(data);
```

#### Python

```python
import requests

response = requests.get(
    "https://api.csvgetter.com/abc123",
    params={"type": "json_records", "sql": "SELECT * FROM csvgetter WHERE status='Active'"},
    headers={"Authorization": "Bearer my-secret-token"}  # only if auth is enabled
)
data = response.json()
print(data)
```

#### cURL

```bash
curl -H "Authorization: Bearer my-secret-token" \
  "https://api.csvgetter.com/abc123?type=json_records&sql=SELECT%20*%20FROM%20csvgetter%20LIMIT%205"
```

***

### Next Steps

* **URL Parameters** — Detailed reference for every parameter.
* **The SQL Parameter** — Full SQL query guide with examples.
* **Troubleshooting** — Solutions for every error code.