Global WatchGlobal Watch Docs
API Reference

Endpoints

API Endpoints

This page provides a complete reference for all Global Watch API endpoints. Each endpoint includes request parameters, response formats, and example code.

Base URL

https://api.global.watch/v1

Projects

Projects are the central resource in Global Watch, representing forest areas with geospatial data.

List Projects

Retrieve all projects for the authenticated account.

GET /projects

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 20, max: 100)
statusstringFilter by status: active, archived, draft
searchstringSearch by name or description
sortstringSort field: name, created_at, area_hectares
orderstringSort order: asc, desc

Example Request

curl -X GET "https://api.global.watch/v1/projects?status=active&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Amazon Reserve - Block A",
      "slug": "amazon-reserve-block-a",
      "description": "Primary conservation area",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[-60.0, -3.0], [-60.0, -3.1], [-60.1, -3.1], [-60.1, -3.0], [-60.0, -3.0]]]
      },
      "area_hectares": 1250.5,
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:00:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}

Get Project

Retrieve a single project by ID.

GET /projects/{project_id}

Path Parameters

ParameterTypeDescription
project_idstringThe project ID

Example Request

curl -X GET "https://api.global.watch/v1/projects/proj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Project

Create a new project.

POST /projects

Request Body

FieldTypeRequiredDescription
namestringYesProject name
descriptionstringNoProject description
geometryGeoJSONNoProject boundaries as GeoJSON Polygon

Example Request

curl -X POST "https://api.global.watch/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Conservation Area",
    "description": "Reforestation project in the Atlantic Forest",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[-45.0, -23.0], [-45.0, -23.1], [-45.1, -23.1], [-45.1, -23.0], [-45.0, -23.0]]]
    }
  }'

Example Response

{
  "data": {
    "id": "proj_def456",
    "name": "New Conservation Area",
    "slug": "new-conservation-area",
    "description": "Reforestation project in the Atlantic Forest",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[-45.0, -23.0], [-45.0, -23.1], [-45.1, -23.1], [-45.1, -23.0], [-45.0, -23.0]]]
    },
    "area_hectares": 1111.2,
    "status": "active",
    "created_at": "2024-01-25T09:00:00Z",
    "updated_at": "2024-01-25T09:00:00Z"
  }
}

Update Project

Update an existing project.

PUT /projects/{project_id}

Request Body

FieldTypeDescription
namestringProject name
descriptionstringProject description
geometryGeoJSONProject boundaries
statusstringProject status

Example Request

curl -X PUT "https://api.global.watch/v1/projects/proj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amazon Reserve - Block A (Updated)",
    "description": "Updated description"
  }'

Delete Project

Delete a project. The project must be archived first.

DELETE /projects/{project_id}

Projects must be archived before deletion. Active projects cannot be deleted directly.

Archive Project

Archive a project.

POST /projects/{project_id}/archive

Restore Project

Restore an archived project.

POST /projects/{project_id}/restore

Assets

Assets represent tracked items within projects, such as equipment, monitoring stations, or points of interest.

List Assets

Retrieve all assets for a project.

GET /projects/{project_id}/assets

Query Parameters

ParameterTypeDescription
pageintegerPage number
per_pageintegerItems per page
typestringFilter by asset type
statusstringFilter by status
searchstringSearch by name

Example Request

curl -X GET "https://api.global.watch/v1/projects/proj_abc123/assets" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "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",
        "installation_date": "2024-01-10"
      },
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "per_page": 20,
    "total_pages": 2
  }
}

Get Asset

Retrieve a single asset.

GET /projects/{project_id}/assets/{asset_id}

Create Asset

Create a new asset within a project.

POST /projects/{project_id}/assets

Request Body

FieldTypeRequiredDescription
namestringYesAsset name
typestringYesAsset type
locationGeoJSON PointNoAsset location
statusstringNoAsset status (default: active)
metadataobjectNoCustom metadata

Example Request

curl -X POST "https://api.global.watch/v1/projects/proj_abc123/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weather Station Beta",
    "type": "equipment",
    "location": {
      "type": "Point",
      "coordinates": [-60.0300, -3.1250]
    },
    "metadata": {
      "serial_number": "WS-2024-002",
      "manufacturer": "WeatherTech"
    }
  }'

Update Asset

Update an existing asset.

PUT /projects/{project_id}/assets/{asset_id}

Delete Asset

Delete an asset.

DELETE /projects/{project_id}/assets/{asset_id}

Members

Manage team members and their permissions.

List Members

Retrieve all members of the account.

GET /account/members

Example Response

{
  "data": [
    {
      "id": "user_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "owner",
      "permissions": ["admin"],
      "joined_at": "2024-01-01T00:00:00Z",
      "last_active_at": "2024-01-25T14:30:00Z"
    },
    {
      "id": "user_def456",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "editor",
      "permissions": ["projects:read", "projects:write", "assets:manage"],
      "joined_at": "2024-01-15T10:00:00Z",
      "last_active_at": "2024-01-24T09:15:00Z"
    }
  ],
  "meta": {
    "total": 5
  }
}

Invite Member

Send an invitation to a new team member.

POST /account/members/invite

Request Body

FieldTypeRequiredDescription
emailstringYesEmail address to invite
rolestringYesRole to assign: viewer, editor, admin

Example Request

curl -X POST "https://api.global.watch/v1/account/members/invite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newmember@example.com",
    "role": "editor"
  }'

Update Member Role

Update a member's role.

PUT /account/members/{member_id}

Request Body

FieldTypeDescription
rolestringNew role

Remove Member

Remove a member from the account.

DELETE /account/members/{member_id}

Account

Manage account settings and information.

Get Account

Retrieve account information.

GET /account

Example Response

{
  "data": {
    "id": "acc_abc123",
    "name": "Acme Forest Management",
    "slug": "acme-forest",
    "type": "team",
    "plan": "pro",
    "usage": {
      "hectares": 5250.5,
      "projects": 12,
      "members": 5
    },
    "created_at": "2023-06-01T00:00:00Z"
  }
}

Update Account

Update account settings.

PUT /account

Request Body

FieldTypeDescription
namestringAccount name

Get Usage

Retrieve current usage statistics.

GET /account/usage

Example Response

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "hectares": {
      "current": 5250.5,
      "limit": 10000,
      "percentage": 52.5
    },
    "projects": {
      "active": 12,
      "archived": 3,
      "total": 15
    },
    "members": {
      "current": 5,
      "limit": 10
    },
    "api_requests": {
      "current": 4521,
      "limit": 10000
    }
  }
}

Webhooks

Manage webhook endpoints for receiving event notifications.

List Webhooks

Retrieve all configured webhooks.

GET /webhooks

Create Webhook

Create a new webhook endpoint.

POST /webhooks

Request Body

FieldTypeRequiredDescription
urlstringYesWebhook endpoint URL
eventsarrayYesEvents to subscribe to
secretstringNoSigning secret (auto-generated if not provided)

Example Request

curl -X POST "https://api.global.watch/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/globalwatch",
    "events": ["project.created", "project.updated", "asset.created"]
  }'

Update Webhook

Update a webhook configuration.

PUT /webhooks/{webhook_id}

Delete Webhook

Delete a webhook.

DELETE /webhooks/{webhook_id}

Test Webhook

Send a test event to a webhook endpoint.

POST /webhooks/{webhook_id}/test

Error Codes

CodeDescription
VALIDATION_ERRORRequest validation failed
NOT_FOUNDResource not found
UNAUTHORIZEDAuthentication required
FORBIDDENInsufficient permissions
RATE_LIMITEDToo many requests
CONFLICTResource conflict (e.g., duplicate slug)
INTERNAL_ERRORServer error

Example Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      },
      {
        "field": "geometry.coordinates",
        "message": "Polygon must have at least 4 coordinates"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Authentication

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

Webhooks

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

On this page

API EndpointsBase URLProjectsList ProjectsGet ProjectCreate ProjectUpdate ProjectDelete ProjectArchive ProjectRestore ProjectAssetsList AssetsGet AssetCreate AssetUpdate AssetDelete AssetMembersList MembersInvite MemberUpdate Member RoleRemove MemberAccountGet AccountUpdate AccountGet UsageWebhooksList WebhooksCreate WebhookUpdate WebhookDelete WebhookTest WebhookError CodesRelated Documentation