Run with PHP SDK

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 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

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):

export FETCH_HIVE_API_KEY=fhk_...

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

Or pass the key explicitly:

$client = new FetchHive(['api_key' => 'fhk_...']);

See API Keys for how to create and rotate keys.

Basic example

Start a Hive Agent run and read the accepted response:

<?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.

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

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.

$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 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

$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:

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 for status code meanings.

Next steps

Invoke from Code - Overview of starting runs from your app
Run with Python SDK
Run with Node.js SDK
Run with Ruby SDK
Invoke - Full endpoint reference

Getting Started

Live Chat

Prompts

Workflows

Hive Agents

Agents

Knowledge Bases

Experiments

Your Workspace

Monitoring

User Tracking

Resources

Installation

Authentication

Basic example

Method reference

Handling the response

Configuration

Errors

Links

Next steps

​Installation

​Authentication

​Basic example

​Method reference

​Handling the response

​Configuration

​Errors

​Links

​Next steps

Installation

Authentication

Basic example

Method reference

Handling the response

Configuration

Errors

Links

Next steps