Skip to main content

API Reference

This page provides quick reference for the Terragnos Core API. For complete API documentation, see the OpenAPI specification or use the interactive API explorer.

Quick Reference​

Base URL​

https://core.example.com/v1

Authentication​

All requests require a JWT token:

Authorization: Bearer <your-jwt-token>

Common Endpoints​

Objects​

MethodEndpointDescription
GET/v1/objectsList objects with optional filtering and pagination
GET/v1/objects/{id}Get object by ID (supports asOf parameter for time-travel)
POST/v1/objectsCreate new object
PATCH/v1/objects/{id}Update object (requires If-Match header for optimistic locking)
DELETE/v1/objects/{id}Delete object
GET/v1/objects/{id}/historyGet object history (transaction and valid time)

Object Types​

MethodEndpointDescription
GET/v1/object-typesList object types
GET/v1/object-types/{id}Get object type
POST/v1/object-typesCreate object type
PATCH/v1/object-types/{id}Update object type
DELETE/v1/object-types/{id}Delete object type

Workflows​

MethodEndpointDescription
GET/v1/workflowsList workflows
GET/v1/workflows/{id}Get workflow definition
POST/v1/workflowsCreate workflow state machine
POST/v1/objects/{id}/workflow/transitionsTrigger workflow transition
GET/v1/objects/{id}/workflow/explain-transitionsExplain available transitions and guards

Automation​

MethodEndpointDescription
GET/v1/automation/rulesList automation rules
POST/v1/automation/rulesCreate automation rule
GET/v1/automation/rules/{id}Get automation rule definition
PATCH/v1/automation/rules/{id}Update automation rule
POST/v1/automation/rules/{id}/publishPublish rule version
GET/v1/automation/rules/{id}/runsList rule execution history
GET/v1/automation/rules/{id}/runs/{runId}Get detailed execution results
POST/v1/automation/triggers/{slug}Trigger webhook automation

Layers​

MethodEndpointDescription
GET/v1/layers/objectsGet GeoJSON layer
GET/v1/layers/objects/streamStream GeoJSON (NDJSON)
GET/v1/layers/tiles/{layer}/{z}/{x}/{y}Get vector tile (MVT)
GET/v1/layers/ogc/featuresOGC API Features

Relations​

MethodEndpointDescription
GET/v1/relationsList relations
POST/v1/relationsCreate relation
PATCH/v1/relations/{id}Update relation
DELETE/v1/relations/{id}Delete relation

Query Service​

MethodEndpointDescription
GET/v1/queries/objectsSimple DTO-based query with filters
POST/v1/queries/objects/runAdvanced JSON DSL query with aggregations and complex filters

Platform Management​

MethodEndpointDescription
GET/v1/health/liveLiveness check
GET/v1/health/readyReadiness check
GET/v1/auth/meCurrent identity
GET/v1/licenseLicense status
POST/v1/licenseInstall license
GET/v1/permissions/policyGet RBAC policy
PUT/v1/permissions/policyUpdate RBAC policy
GET/v1/audit/eventsList audit events
GET/v1/audit/events/{id}/proofVerify audit event

Complete API Documentation​

OpenAPI Specification​

The complete REST API specification is available at:

Import this into:

GraphQL Schema​

The GraphQL schema is available at:

Use with GraphQL clients:

  • GraphQL Playground
  • Apollo Studio
  • Altair GraphQL Client

SDKs​

For easier integration, use the official SDKs:

SDKs provide type-safe interfaces and handle authentication automatically.

Error Codes​

CodeMeaningCommon Causes
400Bad RequestInvalid request data, missing required fields
401UnauthorizedMissing or invalid JWT token
403ForbiddenInsufficient permissions, license limit exceeded
404Not FoundResource doesn't exist
409ConflictOptimistic locking conflict, duplicate resource
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error, database connection issue

Rate Limiting​

Default limits:

  • Window: 60 seconds
  • Limit: 120 requests per window

When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Pagination​

List endpoints support pagination:

GET /v1/objects?limit=25&offset=0

Response includes pagination metadata:

{
  "items": [...],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 150,
    "hasMore": true
  }
}

Time-Travel Queries​

Many read endpoints support time-travel using the asOf parameter:

# Get object state at specific time
GET /v1/objects/{id}?asOf=2024-01-15T10:30:00Z

# List objects as they existed at a point in time
GET /v1/objects?asOf=2024-01-15T10:30:00Z

# Get layer data at specific time
GET /v1/layers/objects?asOf=2024-01-15T10:30:00Z

The asOf parameter accepts ISO 8601 timestamps. Returns the state of data at that point in time, enabling historical queries and audit trails.

Versioning​

The API uses URL-based versioning:

  • Current version: v1
  • Future versions: v2, v3, etc.

Breaking changes only occur in major version updates.