Skip to main content

​
API Reference

This section provides comprehensive documentation for all GeoFlow APIs. GeoFlow exposes several service APIs for integration with external systems and automation.

​
Service APIs

​
GeoFlow App API

RESTful API for the main application interface. Base URL: http://localhost:3000/api (development)
Authentication: JWT Bearer token
Format: JSON

​
Convex Backend API

GraphQL and REST API for data operations. Base URL: http://localhost:3210 (development)
Authentication: Convex session tokens
Format: JSON/GraphQL

​
PDAL Worker API

Processing API for geospatial data operations. Base URL: http://localhost:3002/api (development)
Authentication: API key
Format: JSON

​
Motia Workflow API

Workflow execution and management API. Base URL: http://localhost:4010 (development)
Authentication: API key
Format: JSON

​
MCP Server API

AI-powered geospatial analysis API. Base URL: http://localhost:8000 (development)
Authentication: API key
Format: JSON

​
Authentication

​
JWT Authentication

# Include in request headers
Authorization: Bearer <your-jwt-token>

​
API Key Authentication

# Include in request headers
X-API-Key: <your-api-key>

​
Convex Authentication

// Client-side authentication
import { ConvexReactClient } from 'convex/react'

const convex = new ConvexReactClient(process.env.CONVEX_URL!)
await convex.authenticate(userToken)

​
Response Format

All APIs return JSON responses with consistent structure: 
{
  "success": true,
  "data": { ... },
  "error": null,
  "timestamp": "2024-01-15T10:30:00Z"
}
Error responses: 
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": { ... }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Rate Limiting

  • Authenticated requests: 1000 requests per hour
  • Anonymous requests: 100 requests per hour
  • Processing jobs: 10 concurrent jobs per user
Rate limit headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Error Codes

CodeDescription
VALIDATION_ERRORInvalid request parameters
AUTHENTICATION_ERRORInvalid or missing credentials
AUTHORIZATION_ERRORInsufficient permissions
NOT_FOUNDResource not found
RATE_LIMITEDToo many requests
INTERNAL_ERRORServer error
PROCESSING_ERRORData processing failed

​
SDKs and Libraries

​
JavaScript/TypeScript

npm install @geoflow/geoflow-sdk

import { GeoFlowClient } from '@geoflow/geoflow-sdk'

const client = new GeoFlowClient({
  apiKey: 'your-api-key',
  baseURL: 'https://your-geoflow-instance.com'
})

// Upload file
const file = await client.files.upload(fileBuffer, {
  name: 'data.laz',
  type: 'pointcloud'
})

// Create workflow
const workflow = await client.workflows.create({
  name: 'Processing Pipeline',
  steps: [...]
})

// Execute workflow
const execution = await client.workflows.execute(workflow.id, {
  inputFileId: file.id
})

​
Python

pip install geoflow-python

from geoflow import GeoFlowClient

client = GeoFlowClient(
    api_key='your-api-key',
    base_url='https://your-geoflow-instance.com'
)

# Upload and process data
with open('data.laz', 'rb') as f:
    file = client.files.upload(f, name='data.laz')

workflow = client.workflows.create({
    'name': 'Analysis Pipeline',
    'steps': [...]
})

execution = client.workflows.execute(workflow['id'], {
    'input_file_id': file['id']
})

​
Webhooks

GeoFlow can send webhook notifications for important events:

​
Supported Events

  • workflow.started - Workflow execution started
  • workflow.completed - Workflow execution completed
  • workflow.failed - Workflow execution failed
  • file.processed - File processing completed
  • user.created - New user account created

​
Webhook Payload

{
  "event": "workflow.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "workflowId": "wf-123",
    "executionId": "exec-456",
    "status": "completed",
    "result": { ... },
    "duration": 150000
  }
}

​
Webhook Security

Webhooks include an X-Webhook-Signature header for verification: 
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

​
Versioning

API versioning follows semantic versioning:
  • Breaking changes: New major version (e.g., v2/)
  • New features: New minor version (e.g., v1.1/)
  • Bug fixes: Patch versions (backward compatible)
Current version: v1.0 Specify version in URL path: 
https://api.geoflow.com/v1/workflows

​
Support

For API support: