API Reference

Global Watch API Reference

The Global Watch API enables developers to integrate forest project management capabilities into their applications. This section provides comprehensive documentation for all API endpoints, authentication methods, and integration patterns.

Overview

The Global Watch API is a RESTful API that uses:

JSON for request and response bodies
Bearer tokens for authentication
Standard HTTP methods (GET, POST, PUT, DELETE)
Conventional HTTP status codes for responses

Base URL

All API requests should be made to:

https://api.global.watch/v1

For development and testing:

http://localhost:54321/rest/v1

API Sections

Authentication

Learn how to authenticate API requests using API keys and OAuth tokens.

Endpoints

Complete reference for all available API endpoints with request/response examples.

Webhooks

Configure webhooks to receive real-time notifications about events in your account.

Quick Start

1. Get Your API Key

Log in to your Global Watch account
Navigate to Settings → API Keys
Click Generate New Key
Copy and securely store your API key

API keys provide full access to your account. Never share them publicly or commit them to version control.

2. Make Your First Request

Test your API key by fetching your account information:

curl -X GET "https://api.global.watch/v1/account" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

3. Explore the API

Once authenticated, you can:

List Projects - GET /projects
Create Assets - POST /projects/{id}/assets
Manage Members - GET /account/members
Track Usage - GET /account/usage

Core Resources

Projects

Projects are the central resource in Global Watch. Each project represents a forest area with:

Geospatial boundaries (GeoJSON)
Calculated area in hectares
Associated assets and documents
Team member assignments

{
  "id": "proj_abc123",
  "name": "Amazon Reserve - Block A",
  "slug": "amazon-reserve-block-a",
  "geometry": {
    "type": "Polygon",
    "coordinates": [...]
  },
  "area_hectares": 1250.5,
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Assets

Assets represent tracked items within projects:

{
  "id": "asset_xyz789",
  "project_id": "proj_abc123",
  "name": "Monitoring Station Alpha",
  "type": "equipment",
  "location": {
    "type": "Point",
    "coordinates": [-60.0217, -3.1190]
  },
  "status": "active",
  "metadata": {
    "serial_number": "MS-2024-001"
  }
}

Members

Team members with roles and permissions:

{
  "id": "user_def456",
  "email": "john@example.com",
  "name": "John Doe",
  "role": "editor",
  "permissions": ["projects.read", "projects.write", "assets.manage"],
  "joined_at": "2024-02-01T08:00:00Z"
}

Response Format

All API responses follow a consistent format:

Success Response

{
  "data": {
    // Resource data
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

List Response (Paginated)

{
  "data": [
    // Array of resources
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid project geometry",
    "details": [
      {
        "field": "geometry",
        "message": "Polygon must have at least 4 coordinates"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`204`	No Content - Request succeeded with no response body
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing authentication
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server-side error

Rate Limiting

API requests are rate limited to ensure fair usage:

Plan	Requests per Minute	Requests per Day
Free	60	1,000
Pro	300	10,000
Enterprise	1,000	Unlimited

Rate limit headers are included in all responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705312200

SDKs and Libraries

Official SDKs are available for popular languages:

Language	Package	Documentation
JavaScript/TypeScript	`@globalwatch/sdk`	npm
Python	`globalwatch`	PyPI
Go	`globalwatch-go`	GitHub

JavaScript Example

import { GlobalWatch } from '@globalwatch/sdk';

const client = new GlobalWatch({
  apiKey: process.env.GLOBALWATCH_API_KEY,
});

// List all projects
const projects = await client.projects.list();

// Create a new asset
const asset = await client.assets.create({
  projectId: 'proj_abc123',
  name: 'New Monitoring Station',
  type: 'equipment',
  location: {
    type: 'Point',
    coordinates: [-60.0217, -3.1190],
  },
});

Versioning

The API uses URL-based versioning. The current version is v1.

When breaking changes are introduced, a new version will be released. Previous versions will be supported for at least 12 months after deprecation.

Support

Need help with the API?

Documentation: Browse this API reference
Support: Contact api-support@global.watch
Status: Check status.global.watch for API status

Next Steps

Authentication - Set up API authentication
Endpoints - Explore available endpoints
Webhooks - Configure event notifications

API Reference

Authentication

Endpoints

Webhooks

On this page