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

# API Reference

> Authentication, base URL, rate limits, and error format

# API Reference

The agronome.ai API is a RESTful JSON API built with FastAPI. All endpoints require authentication unless noted otherwise.

## Base URL

```
https://staging.agronome.ai/api/v1
```

## Authentication

All API requests require a Firebase Auth bearer token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  https://staging.agronome.ai/api/v1/organizations
```

Obtain a token by signing in with Firebase Authentication (email/password or OAuth). Tokens expire after 1 hour — use Firebase's token refresh mechanism for long-lived sessions.

## Request format

* **Content-Type:** `application/json` for request bodies
* **Path parameters:** Organization-scoped routes use `/organizations/{org_id}/...`
* **Query parameters:** Filtering, pagination, and search use query params

## Response format

All responses follow a consistent JSON structure:

```json theme={null}
{
  "id": "uuid",
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T12:00:00Z",
  ...
}
```

List endpoints return arrays directly:

```json theme={null}
[
  { "id": "uuid-1", ... },
  { "id": "uuid-2", ... }
]
```

## Error format

Errors return appropriate HTTP status codes with a JSON body:

```json theme={null}
{
  "detail": "Field not found"
}
```

| Status | Meaning                                         |
| ------ | ----------------------------------------------- |
| `400`  | Bad request — invalid input or validation error |
| `401`  | Unauthorized — missing or invalid token         |
| `403`  | Forbidden — insufficient permissions (RBAC)     |
| `404`  | Not found                                       |
| `409`  | Conflict — duplicate resource                   |
| `422`  | Validation error — Pydantic schema mismatch     |
| `500`  | Internal server error                           |

## Organization scoping

Most endpoints are scoped to an organization. The `org_id` path parameter is validated against your memberships — you can only access organizations you belong to, with permissions determined by your role.

```
GET  /api/v1/organizations/{org_id}/farms
POST /api/v1/organizations/{org_id}/farms
GET  /api/v1/organizations/{org_id}/drone/jobs
```

## Interactive documentation

This API reference is auto-generated from the live OpenAPI schema. Use the **Try It** panel on any endpoint page to make test requests with your bearer token.