Skip to main content
Integrations are reusable tool definitions — an endpoint URL + method + headers + a JSON schema for arguments — that you can attach to one or more agents. During a call the agent uses the tool’s schema to decide when to call out; ThunderPhone makes the outbound HTTP request on the agent’s behalf using the integration’s saved configuration. See also Function Tools for the shape of the JSON schema an integration’s spec must follow.

​
Endpoints

MethodPathDescription
GET/v1/integrationsList integrations
POST/v1/integrationsCreate an integration
GET/v1/integrations/{integration_id}Retrieve an integration
PATCH/v1/integrations/{integration_id}Update an integration
DELETE/v1/integrations/{integration_id}Delete an integration
POST/v1/integrations/{integration_id}/transferCopy / move to another org
GET/v1/integrations/{integration_id}/versionsList prior configuration revisions
POST/v1/integrations/test-requestProbe an integration endpoint from a sandbox

​
Integration object

{
  "id": "f9b5a1a4-...",
  "display_name": "Weather API",
  "spec": {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Return the current weather for a zip code.",
      "parameters": { /* JSON Schema */ }
    }
  },
  "endpoint_url": "https://api.example.com/weather",
  "endpoint_method": "GET",
  "headers": [
    { "key": "X-Api-Key", "value": "abc..." }
  ],
  "wizard_input": "Use https://api.example.com/weather with X-Api-Key header.",
  "validation_status": "validated",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
FieldTypeDescription
idUUIDIntegration id
display_namestring1–255 chars
specobjectOpenAI-style function tool schema (see Function Tools)
endpoint_urlstringOutbound HTTP URL the tool calls. Empty string when the integration is still being configured
endpoint_methodstringGET, POST, PUT, PATCH, or DELETE. Defaults to POST
headersarrayList of {key, value} pairs sent with every tool invocation
wizard_inputstringFree-form text from the “describe this integration” wizard; kept for audit only
validation_statusstringuntested, validated, error — updated by test-request
created_at, updated_attimestampISO 8601 UTC

​
List integrations

curl https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
Returns an array of Integration objects.

​
Create an integration

curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "abc..." }
    ]
  }'

​
Request fields

FieldTypeRequiredDescription
display_namestringyes1–255 chars
specobjectyesFunction-tool JSON schema. spec.type must be "function"
endpoint_urlstringnoHTTPS URL; defaults to empty string if omitted
endpoint_methodstringnoGET, POST (default), PUT, PATCH, DELETE
headersarrayno[{key, value}] pairs
wizard_inputstringnoFree-form notes
Returns 201 Created with the new Integration object in validation_status="untested".

​
Retrieve / update / delete

GET, PATCH, and DELETE behave conventionally. PATCH accepts any subset of the create fields. Deleting an integration removes it from every agent it was linked to.

​
Transfer an integration

curl -X POST https://api.thunderphone.com/v1/integrations/f9b5a1a4-.../transfer \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_org_id": 77, "mode": "copy"}'
FieldTypeRequiredDescription
target_org_idintegeryes
modestringyescopy or move
namestringnoOverride the copy’s display name
Returns 201 Created for copy / 200 OK for move: 
{ "mode": "copy", "target_org_id": 77, "integration": { /* ... */ } }

​
Version history

curl 'https://api.thunderphone.com/v1/integrations/f9b5a1a4-.../versions?limit=20' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
Response is analogous to Agent versions: {count, results[]} with each result containing id, revision, created_by, snapshot, and changed_fields.

​
Test integration request

Execute a one-off HTTP request against the integration endpoint (from ThunderPhone’s servers) to validate connectivity before linking the integration to an agent. The sandbox enforces SSRF guards — no requests to localhost or private IP ranges. 
curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "abc..." }
  }'
FieldTypeRequiredDescription
urlstringyesHTTPS; http:// is only allowed for localhost during local dev
methodstringyesGET, POST, PUT, PATCH, DELETE
headersobjectnoHeader-name → value map
bodystring | objectnoFor POST/PUT/PATCH; JSON body or raw string
timeout_secondsintegerno1–20 (default 10)
Response
{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}
Response bodies are truncated at 6 kB. SSRF-blocked requests return 400 with code="url_not_allowed".

Agents

Attach integrations to agents via integration_ids.

Function Tools

The JSON schema shape for spec.