Documentação · Desenvolvedores

API v1 — referência

Contrato HTTP de /api/v1 para propriedades, talhões, catálogo de cenas (Sentinel-2 e Landsat) e NDVI processado. Os limites de hectares seguem o plano da conta — os mesmos da interface web. Visão de produto: artigo da API de NDVI.

Autenticação

Gere a chave no perfil. Prefixo tipicamente ndvi_live_.... Envie em todas as rotas:

Authorization: Bearer ndvi_live_...

Sem chave válida → 401 UNAUTHORIZED. A chave plaintext só aparece uma vez na criação.

Limite de hectares

Ao criar ou atualizar um talhão, a área soma no total da conta. Se ultrapassar maxHa do plano:

HTTP 403
{
  "error": {
    "code": "AREA_LIMIT_REACHED",
    "message": "Area limit reached. ..."
  }
}

Liberar área exige excluir (ou reduzir) talhões — por exemplo DELETE .../fields/:fieldSlug.

Endpoints

Identificadores públicos: propertySlug, fieldSlug. Cenas usam o sceneId do catálogo STAC.

Propriedades

GET/api/v1/propertiesListar propriedades acessíveis
POST/api/v1/propertiesCriar — body `{ "name" }`
GET/api/v1/properties/:propertySlugDetalhe + resumo dos talhões
PATCH/api/v1/properties/:propertySlugRenomear — body `{ "name" }` (OWNER)
DELETE/api/v1/properties/:propertySlugExcluir propriedade (OWNER)

Talhões

GET/api/v1/properties/:propertySlug/fieldsListar talhões
POST/api/v1/properties/:propertySlug/fieldsCriar — body `{ "name", "geoJson" }` (Polygon ou MultiPolygon)
GET/api/v1/properties/:propertySlug/fields/:fieldSlugDetalhe do talhão
PATCH/api/v1/properties/:propertySlug/fields/:fieldSlugAtualizar `name` e/ou `geoJson`
DELETE/api/v1/properties/:propertySlug/fields/:fieldSlugExcluir talhão

Cenas e NDVI

GET/api/v1/properties/:propertySlug/fields/:fieldSlug/scenesCatálogo paginado (`nextCursor`; query opcional `cursor`, `limit`)
POST/api/v1/properties/:propertySlug/fields/:fieldSlug/scenes/:sceneId/processDisparar processamento — `202` com `PENDING` / `PROCESSING`
GET/api/v1/scenes/:sceneId/ndvi?propertySlug=...&fieldSlug=...Estatísticas + URLs quando `READY` (query obrigatória)

Ciclo de integração

Na API REST o processamento não é automático: o cliente dispara POST .../process e consulta o NDVI até READY.

POST /api/v1/properties com { "name" } → 201
POST .../fields com nome + GeoJSON → 201 (ou 403 AREA_LIMIT_REACHED)
GET .../scenes → catálogo paginado
POST .../scenes/:sceneId/process → 202 com status: PENDING e imageId
Poll GET /api/v1/scenes/:sceneId/ndvi?propertySlug&fieldSlug até 200 READY

GET .../ndvi sem imagem processada → 404 NOT_FOUND (“Scene image not found.”).

Enquanto processa → 409 CONFLICT com corpo incluindo status: "PENDING" ou "PROCESSING".

Pronto → 200 com estatísticas e URLs de mapa.

Resposta do catálogo de cenas

{
  "scenes": [
    {
      "sceneId": "S2A_MSIL2A_...",
      "capturedAt": "2026-08-01T13:32:41.024Z",
      "cloudCover": 0.33,
      "imageSource": "sentinel_2",
      "imageId": null,
      "status": null,
      "isSelected": false
    }
  ],
  "nextCursor": "2026-06-14T13:23:25.120Z|LC09_..."
}

status fica null até existir imagem processada para aquela cena no talhão.
imageSource pode ser sentinel_2, landsat_8 ou landsat_9.
Paginação: passe nextCursor como query cursor na próxima página.

Resposta NDVI quando READY

{
  "sceneId": "S2A_...",
  "status": "READY",
  "capturedAt": "2026-08-01T13:32:41.024Z",
  "cloudCover": 23.2,
  "imageSource": "sentinel_2",
  "stats": {
    "mean": 0.62,
    "median": 0.64,
    "stdDev": 0.05,
    "p10": 0.54,
    "p90": 0.66,
    "lowAreaPct": 0,
    "pixelCount": 340
  },
  "images": {
    "rgbUrl": "https://...",
    "ndviUrl": "https://..."
  },
  "bounds": {
    "rgb": { "west": 0, "south": 0, "east": 0, "north": 0 },
    "ndvi": { "west": 0, "south": 0, "east": 0, "north": 0 }
  }
}

URLs apontam para blobs públicos (RGB e NDVI) prontos para overlay no mapa. Não há base64 no v1.

Cobertura de nuvem

O cloudCover do catálogo e o do NDVI READY podem diferir. No catálogo a API resolve cobertura associada à cena/talhão; após o processamento, o valor no endpoint NDVI reflete a cobertura efetiva usada na imagem pronta (máscara no perímetro). Prefira o cloudCover do payload READY para regras de negócio sobre a imagem entregue.

Códigos de erro

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "..."
  }
}

UNAUTHORIZEDChave ausente, inválida ou revogada
FORBIDDENPapel insuficiente na propriedade
NOT_FOUNDRecurso inexistente ou inacessível (inclui cena sem imagem)
VALIDATION_ERRORBody ou query inválidos
AREA_LIMIT_REACHEDCriar/atualizar talhão ultrapassa o limite de hectares do plano (`403`)
CONFLICTNDVI ainda não `READY` (`PENDING` / `PROCESSING`) — HTTP `409`
KEY_LIMIT_REACHEDLimite de chaves ativas no perfil
INTERNAL_ERRORErro inesperado do servidor

Exemplo mínimo (curl)

export KEY="ndvi_live_..."
export BASE="https://ndvi.app/api/v1"

# 1) Propriedade
curl -sS -X POST "$BASE/properties" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Fazenda Demo"}'

# 2) Talhão (GeoJSON Polygon)
curl -sS -X POST "$BASE/properties/<propertySlug>/fields" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Talhao 1","geoJson":{"type":"Polygon","coordinates":[[[...]]]}}'

# 3) Cenas
curl -sS "$BASE/properties/<propertySlug>/fields/<fieldSlug>/scenes" \
  -H "Authorization: Bearer $KEY"

# 4) Processar cena
curl -sS -X POST \
  "$BASE/properties/<propertySlug>/fields/<fieldSlug>/scenes/<sceneId>/process" \
  -H "Authorization: Bearer $KEY"

# 5) Poll NDVI até READY
curl -sS \
  "$BASE/scenes/<sceneId>/ndvi?propertySlug=<propertySlug>&fieldSlug=<fieldSlug>" \
  -H "Authorization: Bearer $KEY"

Chaves e gestão: /profile. Visão de produto: /artigos/api-ndvi.