Run with PHP SDK

Invoke a workflow deployment from PHP with the fetch-hive/sdk Composer package

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 synchronous and asynchronous runs.

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 synchronously — 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 sync response shape.

Method reference

Key	Type	Required	Description
deployment	string	Yes	The workflow deployment name
variant	string	No	The deployment variant name
inputs	array	No	Key-value pairs for the variables defined on the Start step
async_mode	bool	No	When true, return immediately and deliver the result via webhook
callback_url	string	No	Required when async_mode: true — the HTTPS webhook URL to call when the run finishes
user	string	No	Opaque caller identifier surfaced in User Tracking
metadata	array	No	Flat 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

Async runs and webhooks

Pass async_mode: true to queue the workflow and have Fetch Hive call your webhook 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 Async and Webhooks for the verification flow and signed payload shape.

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 — increase for long-running synchronous workflows

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

Links

• Package on Packagist

• Source on GitHub

Next steps

• Async and Webhooks - Verify callback signatures

• Run with API - The same flow with cURL

• Run with Python SDK

• Run with Node.js SDK

• Run with Ruby SDK

• Invoke Workflow - Full endpoint reference