# 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 /` — 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/` — Fetch Export Data (Alternate Path) Identical behavior to `GET /`. Provided for backward compatibility. *** #### `GET /proxy/` — 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.csvgetter.com/api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.