> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Overview of TrailBase REST APIs including base URLs, versioning, authentication, and error handling

TrailBase provides a comprehensive REST API for authentication, record management, subscriptions, and file operations. All APIs are versioned and follow RESTful conventions.

## Base URLs

TrailBase REST APIs are organized into the following base paths:

* **Authentication**: `/api/auth/v1`
* **Records**: `/api/records/v1`
* **Transactions**: `/api/transaction/v1`
* **Query**: `/api/query/v1`
* **Admin**: `/api/_admin`

All API paths are relative to your TrailBase instance URL (e.g., `https://your-instance.com/api/auth/v1/login`).

## Versioning

TrailBase uses path-based versioning. The current API version is `v1` and is included in the base path for all public APIs.

* Authentication APIs: `/api/auth/v1/*`
* Records APIs: `/api/records/v1/*`

Future versions will be introduced as `/api/auth/v2`, `/api/records/v2`, etc., while maintaining backward compatibility.

## Authentication

TrailBase supports multiple authentication methods:

### Bearer Token Authentication

Include the JWT auth token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  https://your-instance.com/api/records/v1/your_api/records
```

### Cookie-Based Authentication

For web applications hosted on the same origin, TrailBase automatically sets cookies:

* `auth_token`: Short-lived JWT token for authentication
* `refresh_token`: Long-lived token for refreshing auth tokens

### CSRF Protection

For state-changing operations (POST, PATCH, DELETE), you may need to include the CSRF token in the `CSRF-Token` header when using cookie-based authentication.

### Token Refresh

Include the refresh token in the `Refresh-Token` header:

```bash theme={null}
curl -H "Refresh-Token: YOUR_REFRESH_TOKEN" \
  -X POST https://your-instance.com/api/auth/v1/refresh
```

## Request Formats

TrailBase accepts multiple request content types:

### JSON (application/json)

```bash theme={null}
curl -X POST https://your-instance.com/api/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret"}'
```

### Form Data (application/x-www-form-urlencoded)

```bash theme={null}
curl -X POST https://your-instance.com/api/auth/v1/login \
  -d "email=user@example.com" \
  -d "password=secret"
```

### Multipart Form Data (multipart/form-data)

Used for file uploads:

```bash theme={null}
curl -X POST https://your-instance.com/api/records/v1/files \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "field=value" \
  -F "file=@/path/to/file.jpg"
```

## Response Formats

All responses are in JSON format with appropriate HTTP status codes.

### Success Response

```json theme={null}
{
  "id": "abc123",
  "created_at": "2026-03-07T12:00:00Z",
  "data": "example"
}
```

### Error Response

```json theme={null}
{
  "error": "Bad request: invalid email"
}
```

<Note>
  In production mode, error messages are intentionally minimal to avoid leaking internal details. Debug mode provides more detailed error information.
</Note>

## Error Handling

TrailBase uses standard HTTP status codes to indicate success or failure:

### Success Codes

<ResponseField name="200" type="OK">
  Request succeeded, response body contains the result.
</ResponseField>

<ResponseField name="201" type="Created">
  Resource created successfully.
</ResponseField>

<ResponseField name="303" type="See Other">
  Redirect to another URL (typically after successful form submission).
</ResponseField>

### Client Error Codes

<ResponseField name="400" type="Bad Request">
  Invalid request parameters, malformed JSON, or constraint violation.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Authentication required but not provided or invalid.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Authenticated but not authorized to access the resource.
</ResponseField>

<ResponseField name="404" type="Not Found">
  Resource or API endpoint not found.
</ResponseField>

<ResponseField name="405" type="Method Not Allowed">
  API not found or HTTP method not supported for this endpoint.
</ResponseField>

<ResponseField name="409" type="Conflict">
  Resource already exists (e.g., duplicate registration).
</ResponseField>

<ResponseField name="424" type="Failed Dependency">
  External dependency failed (e.g., email service unavailable).
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Rate limit exceeded.
</ResponseField>

### Server Error Codes

<ResponseField name="500" type="Internal Server Error">
  Unexpected server error occurred.
</ResponseField>

### Database Constraint Errors

When database constraints are violated, TrailBase returns `400 Bad Request` with specific error messages:

* `db constraint: check` - CHECK constraint failed
* `db constraint: fk` - Foreign key constraint failed
* `db constraint: not null` - NOT NULL constraint failed
* `db constraint: pk` - Primary key constraint failed
* `db constraint: unique` - UNIQUE constraint failed

## Rate Limiting

Certain endpoints (like password reset and email verification) are rate-limited to prevent abuse. Exceeding rate limits returns `429 Too Many Requests`.

## CORS

TrailBase supports Cross-Origin Resource Sharing (CORS) for web applications. Configure CORS settings in your TrailBase configuration.

## Pagination

List endpoints support cursor-based pagination:

```bash theme={null}
curl "https://your-instance.com/api/records/v1/your_api?limit=20&cursor=abc123"
```

<ParamField query="limit" type="integer">
  Number of records to return (default varies by API, configurable hard limit)
</ParamField>

<ParamField query="cursor" type="string">
  Encrypted cursor from previous response for fetching the next page
</ParamField>

<ParamField query="offset" type="integer">
  Zero-based offset for pagination (alternative to cursor)
</ParamField>

## Filtering

Records API supports filtering via query parameters:

```bash theme={null}
# Filter by field value
curl "https://your-instance.com/api/records/v1/posts?filter[status]=published"

# Multiple filters
curl "https://your-instance.com/api/records/v1/posts?filter[status]=published&filter[author]=john"
```

See the [Records API](/api/records) documentation for detailed filtering syntax.

## Ordering

Results can be ordered by specifying column names:

```bash theme={null}
# Ascending order
curl "https://your-instance.com/api/records/v1/posts?order=created_at"

# Descending order
curl "https://your-instance.com/api/records/v1/posts?order=-created_at"

# Multiple columns
curl "https://your-instance.com/api/records/v1/posts?order=status,-created_at"
```

## Best Practices

1. **Always use HTTPS** in production to protect authentication tokens
2. **Store tokens securely** - never expose tokens in client-side code or logs
3. **Implement token refresh** to maintain sessions without re-authentication
4. **Handle errors gracefully** - check status codes and parse error messages
5. **Use appropriate content types** - JSON for most requests, multipart for file uploads
6. **Respect rate limits** - implement exponential backoff for retry logic
7. **Validate inputs** on the client side to reduce unnecessary API calls

## SDK Support

TrailBase provides TypeScript types for all API endpoints, which can be found in the generated client package. See the [Client Libraries](/client/overview) documentation for more details.