REST API Overview

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

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":"[email protected]","password":"secret"}'

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

curl -X POST https://your-instance.com/api/auth/v1/login \
  -d "[email protected]" \
  -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

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

Always use HTTPS in production to protect authentication tokens
Store tokens securely - never expose tokens in client-side code or logs
Implement token refresh to maintain sessions without re-authentication
Handle errors gracefully - check status codes and parse error messages
Use appropriate content types - JSON for most requests, multipart for file uploads
Respect rate limits - implement exponential backoff for retry logic
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.

REST APIs

Client SDKs

CLI Reference

Base URLs

Versioning

Authentication

Bearer Token Authentication

CSRF Protection

Token Refresh

Request Formats

JSON (application/json)

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

Multipart Form Data (multipart/form-data)

Response Formats

Success Response

Error Response

Error Handling

Success Codes

Client Error Codes

Server Error Codes

Database Constraint Errors

Rate Limiting

CORS

Filtering

Ordering

Best Practices

SDK Support

Build docs developers (and LLMs) love

REST APIs

Client SDKs

CLI Reference

​Base URLs

​Versioning

​Authentication

​Bearer Token Authentication

​Cookie-Based Authentication

​CSRF Protection

​Token Refresh

​Request Formats

​JSON (application/json)

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

​Multipart Form Data (multipart/form-data)

​Response Formats

​Success Response

​Error Response

​Error Handling

​Success Codes

​Client Error Codes

​Server Error Codes

​Database Constraint Errors

​Rate Limiting

​CORS

​Pagination

​Filtering

​Ordering

​Best Practices

​SDK Support

Build docs developers (and LLMs) love

Base URLs

Versioning

Authentication

Bearer Token Authentication

Cookie-Based Authentication

CSRF Protection

Token Refresh

Request Formats

JSON (application/json)

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

Multipart Form Data (multipart/form-data)

Response Formats

Success Response

Error Response

Error Handling

Success Codes

Client Error Codes

Server Error Codes

Database Constraint Errors

Rate Limiting

CORS

Pagination

Filtering

Ordering

Best Practices

SDK Support