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

# API Introduction

> Base URL, response format, versioning, and getting started with the High IQ Cannabis Intelligence API.

## Overview

The High IQ API is a RESTful JSON API built on [Hono](https://hono.dev/) and deployed to Vercel Edge Functions. It provides access to cannabis strain data, AI-powered report generation, label scanning, and research intelligence.

All endpoints are prefixed with `/api/v1/` and return consistent JSON response envelopes.

## Base URL

<Tabs>
  <Tab title="Production">
    ```
    https://api.thisiswhyimhigh.com/api/v1/
    ```
  </Tab>

  <Tab title="Local Development">
    ```
    http://localhost:3001/api/v1/
    ```
  </Tab>
</Tabs>

## Versioning

The API uses URL-based versioning. The current and only version is `v1`. All endpoints are served under the `/api/v1/` prefix.

```
https://api.thisiswhyimhigh.com/api/v1/strains
https://api.thisiswhyimhigh.com/api/v1/strains/search?q=blue+dream
https://api.thisiswhyimhigh.com/api/v1/notebooks/stream/batch
```

When breaking changes are introduced, a new version prefix (e.g., `/api/v2/`) will be added while maintaining backward compatibility on existing versions.

## Response Format

Every API response follows a consistent envelope format, making it predictable to parse on the client side.

### Success Response

All successful responses return `success: true` with a `data` field containing the response payload and an optional `meta` field for pagination and request metadata.

```json theme={null}
{
  "success": true,
  "data": {
    "strain": {
      "id": 42,
      "name": "Blue Dream",
      "type": "hybrid"
    }
  },
  "meta": {
    "timestamp": "2026-02-16T12:00:00.000Z",
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

### Success Response with Pagination

List endpoints include pagination metadata when applicable.

```json theme={null}
{
  "success": true,
  "data": [
    { "id": 1, "name": "Blue Dream" },
    { "id": 2, "name": "OG Kush" }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 1247,
      "hasMore": true
    },
    "timestamp": "2026-02-16T12:00:00.000Z",
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

### Error Response

All error responses return `success: false` with a structured `error` object containing a machine-readable `code` and a human-readable `message`.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Strain not found: purple-unicorn",
    "details": {
      "resource": "Strain",
      "id": "purple-unicorn"
    }
  },
  "meta": {
    "timestamp": "2026-02-16T12:00:00.000Z",
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "/api/v1/strains/slug/purple-unicorn",
    "method": "GET"
  }
}
```

## TypeScript Interfaces

The API response types are defined in TypeScript for type-safe client consumption.

```typescript theme={null}
// Success response
interface ApiSuccessResponse<T = unknown> {
  success: true;
  data: T;
  meta?: {
    pagination?: {
      limit: number;
      offset: number;
      total: number;
      hasMore?: boolean;
    };
    timestamp?: string;
    requestId?: string;
    [key: string]: unknown;
  };
}

// Error response
interface ApiErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: unknown;
    stack?: string; // Only in non-production environments
  };
  meta?: {
    timestamp?: string;
    requestId?: string;
    path?: string;
    method?: string;
  };
}
```

## Quick Start

Fetch a strain by slug with a simple `curl` command:

```bash theme={null}
curl -s "https://api.thisiswhyimhigh.com/api/v1/strains/slug/blue-dream/complete" | jq
```

Search for strains:

```bash theme={null}
curl -s "https://api.thisiswhyimhigh.com/api/v1/strains/search?q=gorilla+glue&limit=5" | jq
```

## Request IDs

Every response includes a unique `requestId` in the `meta` object. Include this ID when reporting issues or debugging unexpected behavior. The request ID is generated server-side and is consistent across the entire request lifecycle.

<Note>
  Stack traces in error responses are only included in non-production environments. Production errors return structured codes and messages without exposing internal details.
</Note>

## Content Type

The API accepts and returns `application/json` for all standard endpoints. Streaming endpoints (SSE) return `text/event-stream`. Set your request headers accordingly:

```bash theme={null}
curl -X POST "https://api.thisiswhyimhigh.com/api/v1/notebooks/stream/batch" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"sectionKeys": ["overview"]}'
```

## HTTP Methods

| Method   | Usage                                                              |
| -------- | ------------------------------------------------------------------ |
| `GET`    | Read resources (strains, search, cache stats)                      |
| `POST`   | Create resources, trigger operations (reports, scans, submissions) |
| `PUT`    | Full resource replacement (rare)                                   |
| `PATCH`  | Partial resource updates                                           |
| `DELETE` | Remove resources                                                   |

Most public-facing endpoints are `GET` requests. `POST` is used for operations that require a request body, such as report streaming and label scanning.