> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get data flowing through the Leaf API in 15 minutes. Create an account, authenticate, connect a provider or upload a file, and retrieve field operations.

This guide takes you from zero to retrieving processed agricultural data. You'll create an account, get a token, create a Leaf user, and connect a data source.

## Before you begin

You need:

1. **A Leaf account.** [Contact Sales](https://withleaf.io/account/get-a-demo) or your Customer Success representative to register an account.
2. **Provider API credentials** (if connecting to a provider). Complete the provider's developer/partner agreement and obtain your client ID and secret. Leaf can help with introductions if needed.
3. **An HTTP client.** cURL works, or use the [Leaf Postman Collection](https://github.com/Leaf-Agriculture/Leaf-API-Postman-Collection).

<Tip>
  Leaf does not have a separate test environment. Create distinct API owner accounts for testing and production, e.g. `leaf-test@yourcompany.com` and `leaf-prod@yourcompany.com`.
</Tip>

## Step 1: Get your token

After registering, authenticate to get a JWT token. This token goes in the `Authorization: Bearer <token>` header of every API request.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Content-Type: application/json' \
    -d '{"username":"your-email@example.com","password":"your-password","rememberMe":"true"}' \
    'https://api.withleaf.io/api/authenticate'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.withleaf.io/api/authenticate",
      headers={"Content-Type": "application/json"},
      json={
          "username": "your-email@example.com",
          "password": "your-password",
          "rememberMe": "true"
      }
  )
  token = response.json()["id_token"]
  ```

  ```javascript JavaScript theme={null}
  const axios = require("axios");

  axios.post("https://api.withleaf.io/api/authenticate", {
    username: "your-email@example.com",
    password: "your-password",
    rememberMe: "true",
  })
    .then(({ data }) => {
      const token = data.id_token;
      console.log(token);
    })
    .catch(console.error);
  ```
</CodeGroup>

The response contains your token:

```json theme={null}
{
  "id_token": "eyJhbGciOi..."
}
```

With `rememberMe` set to `"true"`, the token lasts 30 days. Set it to `"false"` for a 24-hour token. See [Authentication](/getting-started/authentication) for full details.

## Step 2: Create a Leaf user

A Leaf user typically represents a grower. Each Leaf user holds provider credentials, fields, and field operations. Create one with a `POST` request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Test Grower","email":"grower@example.com"}' \
    'https://api.withleaf.io/services/usermanagement/api/users'
  ```

  ```python Python theme={null}
  response = requests.post(
      "https://api.withleaf.io/services/usermanagement/api/users",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={"name": "Test Grower", "email": "grower@example.com"}
  )
  leaf_user = response.json()
  leaf_user_id = leaf_user["id"]
  ```

  ```javascript JavaScript theme={null}
  axios.post(
    "https://api.withleaf.io/services/usermanagement/api/users",
    { name: "Test Grower", email: "grower@example.com" },
    { headers: { Authorization: `Bearer ${token}` } }
  )
    .then((userResponse) => {
      const leafUserId = userResponse.data.id;
      console.log(leafUserId);
    })
    .catch(console.error);
  ```
</CodeGroup>

Save the returned `id`. You'll use it in every subsequent call for this grower.

## Step 3: Connect data

You have two options for getting data into Leaf:

**Option A: Connect a provider.** Attach provider credentials to the Leaf user so Leaf automatically syncs their data. Each provider has a specific credentials schema. See the [provider authentication docs](/providers/overview) for details.

**Option B: Upload files directly.** If the grower has machine files on a USB drive or local storage, you can upload them through the API or use Leaf's Magic Link file upload widget.

<Warning>
  During development, avoid repeatedly connecting large provider accounts. This consumes your testing acre allotment. Use the `customDataSync` configuration to limit which fields Leaf processes.
</Warning>

## Step 4: Retrieve your data

Once Leaf processes the connected or uploaded data, you can retrieve machine files and field operations.

List machine files for the Leaf user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/operations/api/files?leafUserId=LEAF_USER_ID'
  ```

  ```python Python theme={null}
  files = requests.get(
      "https://api.withleaf.io/services/operations/api/files",
      headers={"Authorization": f"Bearer {token}"},
      params={"leafUserId": leaf_user_id}
  ).json()
  ```

  ```javascript JavaScript theme={null}
  axios.get("https://api.withleaf.io/services/operations/api/files", {
    headers: { Authorization: `Bearer ${token}` },
    params: { leafUserId: leafUserId },
  })
    .then((files) => console.log(files.data))
    .catch(console.error);
  ```
</CodeGroup>

List field operations for the Leaf user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/operations/api/operations?leafUserId=LEAF_USER_ID'
  ```

  ```python Python theme={null}
  operations = requests.get(
      "https://api.withleaf.io/services/operations/api/operations",
      headers={"Authorization": f"Bearer {token}"},
      params={"leafUserId": leaf_user_id}
  ).json()
  ```

  ```javascript JavaScript theme={null}
  axios.get("https://api.withleaf.io/services/operations/api/operations", {
    headers: { Authorization: `Bearer ${token}` },
    params: { leafUserId: leafUserId },
  })
    .then((operations) => console.log(operations.data))
    .catch(console.error);
  ```
</CodeGroup>

<Note>
  Field operations require field boundaries. Without boundaries, Leaf converts machine files and produces file summaries, but cannot create operations. You can sync boundaries from a provider or create them manually via the API.
</Note>

If this worked, the machine files request returns a response object whose `operations` array contains the discovered machine files for the Leaf user. Once Leaf has both files and field boundaries, the operations request returns standardized operations for that grower.

## Step 5: Set up alerts

Instead of polling the API, set up webhooks to get notified when new data is ready. At a minimum, subscribe to field events, field boundary events, machine file events, and field operation events.

See the [Alerts documentation](/alerts/overview) for the full list of available events and setup instructions.

## What you built

You now have a working Leaf integration: an authenticated API owner, a Leaf user representing a grower, a connected data source, and the ability to retrieve processed field operations. From here:

* [Core Concepts](/getting-started/core-concepts): Understand how the data pipeline works.
* [Provider Authentication](/providers/overview): Connect to John Deere, Climate FieldView, CNHi, CNHI FieldOps, and other providers.
* [Machine Data](/machine-data/overview): Understand how Leaf processes machine files into field operations.
* [Fields](/fields/overview): Manage field boundaries from providers or create your own.
* [Configurations](/configuration/overview): Control how Leaf processes and syncs data.