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

# Run with PHP SDK

> Start a Hive Agent run from PHP with the fetch-hive/sdk Composer package

Use the official `fetch-hive/sdk` Composer package when you want to start a Hive Agent run from PHP. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with an idiomatic facade and handles authentication.

Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.

## Installation

```bash theme={null}
composer require fetch-hive/sdk
```

The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.

## Authentication

Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the client reads it automatically):

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```php theme={null}
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
```

Or pass the key explicitly:

```php theme={null}
$client = new FetchHive(['api_key' => 'fhk_...']);
```

See [API Keys](../workspace/api-keys) for how to create and rotate keys.

## Basic example

Start a Hive Agent run and read the accepted response:

```php theme={null}
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$result = $client->invokeHiveAgent([
    'hive_agent'   => 'YOUR_HIVE_AGENT_ID',
    'objective'    => 'Research competitors and summarize verified findings',
    'callback_url' => 'https://example.com/hive-agent-callback',
    'sources'      => ['website_urls' => ['https://example.com']],
    'metadata'     => ['customer_id' => 'cus_123'],
]);

echo $result['run_id'];
echo $result['request_id'];
echo $result['webhook_secret'];
```

`invokeHiveAgent` returns the parsed JSON body as an associative array as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).

## Method reference

| Key            | Type     | Required | Description                                                                                                       |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent`   | `string` | Yes      | The Hive Agent ID from the dashboard                                                                              |
| `objective`    | `string` | Yes      | Specific objective for the planner to create work nodes from                                                      |
| `callback_url` | `string` | Yes      | HTTPS URL that receives the signed terminal callback                                                              |
| `sources`      | `array`  | No       | Grounded context from websites, assets, or knowledge bases in the workspace                                       |
| `metadata`     | `array`  | No       | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |

The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.

## Handling the response

Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.

```php theme={null}
$result = $client->invokeHiveAgent([
    'hive_agent'   => 'YOUR_HIVE_AGENT_ID',
    'objective'    => 'Research competitors and summarize verified findings',
    'callback_url' => 'https://example.com/hive-agent-callback',
]);

echo $result['run_id'];          // queued run identifier
echo $result['request_id'];      // use this to look up the run in Logs
echo $result['status'];          // usually "pending"
echo $result['webhook_secret'];  // verify the signed callback
```

Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.

## Configuration

| Option     | Default                        | Description                     |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key`  | `FETCH_HIVE_API_KEY` env var   | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL       |
| `timeout`  | `120`                          | Request timeout in seconds      |

```php theme={null}
$client = new FetchHive([
    'api_key'  => 'fhk_...',
    'base_url' => 'https://api.fetchhive.com/v1',
    'timeout'  => 60.0,
]);
```

## Errors

Missing `callback_url` throws `InvalidArgumentException` before a request is sent. Non-2xx responses throw `FetchHive\Sdk\Exception\ApiException` carrying the status code and response body:

```php theme={null}
use FetchHive\Sdk\Exception\ApiException;

try {
    $result = $client->invokeHiveAgent([
        'hive_agent'   => 'YOUR_HIVE_AGENT_ID',
        'objective'    => 'Research competitors and summarize verified findings',
        'callback_url' => 'https://example.com/hive-agent-callback',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}
```

See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for status code meanings.

## Links

* [Package on Packagist](https://packagist.org/packages/fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/php-sdk)

## Next steps

* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Invoke](../api-reference/hive-agents/invoke) - Full endpoint reference