Skip to main content
Use the official fetch-hive/sdk Composer package when you want to invoke a workflow deployment from PHP. The SDK wraps the public POST /v1/workflow/invoke endpoint, handles authentication, and supports both direct responses and callback delivery.

​
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

Run a workflow deployment directly. The call blocks until the workflow finishes: 
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$run = $client->invokeWorkflow([
    'deployment' => 'YOUR_DEPLOYMENT_NAME',
    'variant'    => 'YOUR_VARIANT_NAME',
    'inputs'     => ['topic' => 'State of enterprise AI in 2026'],
]);

echo $run['run_status'] . PHP_EOL;
echo $run['output'];
See the direct response shape.

​
Method reference

KeyTypeRequiredDescription
deploymentstringYesThe workflow deployment name
variantstringNoThe deployment variant name
inputsarrayNoKey-value pairs for the variables defined on the Start step
async_modeboolNoWhen true, return immediately and deliver the result by signed callback
callback_urlstringNoRequired when async_mode: true - the HTTPS callback URL to call when the run finishes
userstringNoOpaque caller identifier surfaced in User Tracking
metadataarrayNoFlat caller-defined metadata for audit and log filtering. See Invoke metadata
invokeWorkflow builds the request body for you. When you pass async_mode: true, the SDK sends: 
{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}

​
Handling the response

$run = $client->invokeWorkflow([
    'deployment' => 'my-workflow',
    'variant'    => 'default',
]);

echo $run['run_status'];      // "completed" | "failed" | "running" | "queued"
echo $run['output'];          // final workflow output
echo $run['request_id'];      // use this to look up the run in Logs

​
Callback delivery

Pass async_mode: true to return immediately and have Fetch Hive call your callback URL when the run finishes: 
$run = $client->invokeWorkflow([
    'deployment'   => 'YOUR_DEPLOYMENT_NAME',
    'variant'      => 'YOUR_VARIANT_NAME',
    'inputs'       => ['topic' => 'State of enterprise AI in 2026'],
    'async_mode'   => true,
    'callback_url' => 'https://example.com/callback',
]);

echo 'Queued: ' . $run['run_status'] . PHP_EOL;
echo 'Webhook secret: ' . $run['webhook_secret'];
Store the webhook_secret so you can verify the signature on the incoming callback. See Callback Delivery and Webhook Triggers for the verification flow and signed payload shape.

​
Configuration

OptionDefaultDescription
api_keyFETCH_HIVE_API_KEY env varBearer token from the dashboard
base_urlhttps://api.fetchhive.com/v1Override the API base URL
timeout120Request timeout in seconds - increase for long-running direct workflow requests
$client = new FetchHive([
    'api_key'  => 'fhk_...',
    'base_url' => 'https://api.fetchhive.com/v1',
    'timeout'  => 600.0,
]);

​
Errors

Non-2xx responses throw FetchHive\Sdk\Exception\ApiException carrying the status code and response body: 
use FetchHive\Sdk\Exception\ApiException;

try {
    $run = $client->invokeWorkflow([
        'deployment' => 'my-workflow',
        'variant'    => 'default',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}
See Error Handling for workflow-specific failure cases and Errors and Rate Limits for HTTP status code meanings.

​
Next steps