Skip to main content
POST /v1/prompt/invoke Run a prompt deployment from your own app or service.

​
Authentication

Send your workspace API key in the Authorization header. 
Authorization: Bearer YOUR_API_KEY

​
Request body

Open Prompts, then Deployments, open the deployment variant you want to run, and click Code Snippet to see this request shape in Fetch Hive.
FieldTypeRequiredDescription
deploymentstringYesThe prompt deployment name
variantstringYesThe deployment variant name
inputsobjectNoKey-value pairs for the prompt variables
streamingbooleanNoStream response events instead of waiting for one final JSON response
metadataobjectNoFlat caller-defined metadata for audit and log filtering. This is not used as prompt input.
metadata must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or null. Arrays and nested objects are rejected before the run starts. POST /v1/prompt/invoke does not accept top-level image_urls or document attachments. If a deployed prompt uses an image URL message part, configure that image URL in the prompt editor or bind it through an inputs variable in the prompt content. For runtime image/document attachments, use POST /v1/agent/invoke. Valid: 
{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}
Invalid: 
{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}

​
Response

If streaming is true, Fetch Hive returns a stream of events. If the provider fails after the stream has opened, Fetch Hive sends a final error event before closing the stream. Example reasoning event: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
Example response event: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
Example final usage event: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}
Example error event: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "error",
  "error": "cohere provider stream error: HTTP 400: invalid request",
  "message": "cohere provider stream error: HTTP 400: invalid request",
  "provider": "cohere",
  "error_type": "provider_stream_error",
  "status_code": 502
}
If streaming is false, Fetch Hive returns one JSON response. Provider execution failures return 502 Bad Gateway with an error message. 
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "The request asks for a short summary.",
  "response": "Fetch Hive helps teams ship AI products faster.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}

​
Example

curl 'https://api.fetchhive.com/v1/prompt/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "inputs": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "streaming": true
  }' \
  --compressed

​
Webhook trigger

POST /v1/prompt/webhooks/{prompt_endpoint_id}/variants/{variant_id} Use a prompt webhook trigger when an external service should start a deployed prompt variant without a workspace API key. The request must include the prompt endpoint webhook secret in X-Fetch-Hive-Webhook-Secret. If a third-party tool cannot set custom headers, use ?secret=YOUR_WEBHOOK_SECRET as a fallback. Webhook prompt triggers always use callback delivery. Include async.callback_url; Fetch Hive returns 202 with request_id and run_status: "running", then delivers either prompt.completed or prompt.failed to the callback URL. 
curl 'https://api.fetchhive.com/v1/prompt/webhooks/YOUR_PROMPT_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
  -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "user": "external-user-1",
    "async": {
      "callback_url": "https://example.com/callback"
    }
  }'
inputs must be an object. Every variable declared on the selected deployed prompt version must be present, but values may be empty strings or null when you intentionally want a blank render. Extra input keys are allowed. metadata follows the same flat scalar-only rule as normal prompt invokes and appears in log filtering. Fetch Hive signs the outbound callback with the same webhook secret used for inbound trigger authentication. Callback data contains response on prompt.completed and error on prompt.failed; use the top-level event_type and request_id for terminal state and correlation.