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:

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:

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)

curl -X POST https://your-instance.com/api/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"secret"}'

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

curl -X POST https://your-instance.com/api/auth/v1/login \
  -d "email=[e-mail]" \
  -d "password=secret"

Multipart Form Data (multipart/form-data)

Used for file uploads:

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

{
  "id": "abc123",
  "created_at": "2026-03-07T12:00:00Z",
  "data": "example"
}

Error Response

{
  "error": "Bad request: invalid email"
}

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

Error Handling

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

Success Codes

200 · OK

Request succeeded, response body contains the result.

201 · Created

Resource created successfully.

303 · See Other

Redirect to another URL (typically after successful form submission).

Client Error Codes

400 · Bad Request

Invalid request parameters, malformed JSON, or constraint violation.

401 · Unauthorized

Authentication required but not provided or invalid.

403 · Forbidden

Authenticated but not authorized to access the resource.

404 · Not Found

Resource or API endpoint not found.

405 · Method Not Allowed

API not found or HTTP method not supported for this endpoint.

409 · Conflict

Resource already exists (e.g., duplicate registration).

424 · Failed Dependency

External dependency failed (e.g., email service unavailable).

429 · Too Many Requests

Rate limit exceeded.

Server Error Codes

500 · Internal Server Error

Unexpected server error occurred.

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:

curl "https://your-instance.com/api/records/v1/your_api?limit=20&cursor=abc123"

limit · integer

Number of records to return (default varies by API, configurable hard limit)

cursor · string

Encrypted cursor from previous response for fetching the next page

offset · integer

Zero-based offset for pagination (alternative to cursor)

Filtering

Records API supports filtering via query parameters:

# 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 documentation for detailed filtering syntax.

Ordering

Results can be ordered by specifying column names:

# 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 documentation for more details.