Skip to content
TerraScale Documentation

API Overview

Complete API reference for TerraScale database operations.

Base URL

Section titled “Base URL”
https://api.terrascale.io

All endpoints return JSON responses and use standard HTTP status codes.

Authentication

Section titled “Authentication”

All API requests require authentication. Use one of:

API Key (for database operations)

Section titled “API Key (for database operations)”
Authorization: Bearer ts_live_your_api_key

JWT Token (for management operations)

Section titled “JWT Token (for management operations)”
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

See Authentication for details.

API Sections

Section titled “API Sections”

Common Response Patterns

Section titled “Common Response Patterns”

Success Response

Section titled “Success Response”
{
  "pk": "user#123",
  "sk": "profile",
  "data": {
    "name": "John Doe"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Error Response

Section titled “Error Response”
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Item not found"
}

HTTP Status Codes

Section titled “HTTP Status Codes”
StatusDescription
200OK - Request succeeded
201Created - Resource created
204No Content - Success, no body
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing authentication
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Condition check failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Pagination

Section titled “Pagination”

Paginated endpoints use cursor-based pagination:

Request:

{
  "limit": 20,
  "cursor": null
}

Response:

{
  "items": [...],
  "nextCursor": "eyJsYXN0S2V5Ijo...",
  "count": 20
}

To get the next page, pass the nextCursor value as cursor in the next request.

Rate Limits

Section titled “Rate Limits”

Rate limits depend on your plan tier:

PlanLimit
Free100 requests/second
Pro1,000 requests/second
EnterpriseCustom

When rate limited, the API returns HTTP 429 with a Retry-After header.

See Rate Limits for details.

Required Scopes

Section titled “Required Scopes”
OperationRequired Scope
Read itemsdatabase:read or database:*
Write itemsdatabase:write or database:*
Read repositoriesrepository:read or repository:*
Write repositoriesrepository:write or repository:*

Next Steps

Section titled “Next Steps”