Invoke a Connector via API

Every connector you set up at app.xpander.ai/connectors can be called directly over REST. This page walks the full path end to end: find the connector → get its connection_id → pick an operation → invoke it.

Base URL & Authentication

https://api.xpander.ai

All requests require an API key passed as a header:

x-api-key: YOUR_XPANDER_API_KEY

Your API key is already scoped to your organization — you do not need to pass an organization ID.

The three IDs you need

ID	What it is	Where to get it
`connector_id`	The connector itself (e.g. Firecrawl)	The URL at `app.xpander.ai/connectors/{connector_id}`, or List Tools
`connection_id`	Your org’s authenticated connection to that connector	The `connections[].id` field in List Tools
`operation_id`	The specific action to run	List Connector Operations — accepts the operation’s `id` or its `operationId`

The connector page URL in the app gives you the connector_id — but invoking also requires a connection_id, which is a different UUID. Step 1 below shows how to get it.

Step 1 — Find the connector and its connection

Search your tool catalog by name:

curl "https://api.xpander.ai/v1/tools?type=connector&query=firecrawl" \
  -H "x-api-key: YOUR_XPANDER_API_KEY"

{
  "items": [
    {
      "kind": "connector",
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Firecrawl",
      "status": "ready",
      "total_operations": 6,
      "using_built_in_auth": true,
      "connections": [
        {
          "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "name": "Firecrawl",
          "access_scope": "organizational"
        }
      ]
    }
  ],
  "total": 1
}

Here items[].id is the connector_id and items[].connections[].id is the connection_id.

An empty connections array means the connector isn’t connected yet — create a connection first with Connect Connector (OAuth2 connectors return a connector_page_url to finish auth in the browser).

Step 2 — List the operations

curl "https://api.xpander.ai/v1/tools/connectors/{connector_id}/operations?connection_id={connection_id}" \
  -H "x-api-key: YOUR_XPANDER_API_KEY"

[
  {
    "id": "67e2daf399f31f9c55d127a7",
    "operationId": "FirecrawlScrapingServiceExtractWebpageContent",
    "path": "/scrape",
    "method": "post",
    "pretty_name": "Extract Webpage Content",
    "pretty_description": "Extracts content from a specified webpage URL."
  }
]

Either id or operationId works as the operation_id in the next steps.

Step 3 (optional) — Inspect the operation’s inputs

curl "https://api.xpander.ai/v1/tools/connectors/{connector_id}/connections/{connection_id}/{operation_id}/schema" \
  -H "x-api-key: YOUR_XPANDER_API_KEY"

The response’s input field is a JSON schema with three groups — body_params, query_params, and path_params — which is exactly the structure the invoke call accepts.

Step 4 — Invoke

curl -X POST "https://api.xpander.ai/v1/tools/connectors/{connector_id}/connections/{connection_id}/{operation_id}" \
  -H "x-api-key: YOUR_XPANDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body_params": {
      "url": "https://example.com",
      "formats": ["markdown"]
    }
  }'

The response is the target API’s response, passed through unchanged:

{
  "success": true,
  "data": {
    "markdown": "# Example Domain\n\nThis domain is for use in documentation examples...",
    "metadata": {
      "title": "Example Domain",
      "sourceURL": "https://example.com",
      "statusCode": 200
    }
  }
}

How the request body maps to the target API

Field	Purpose	Example
`body_params`	The JSON body sent to the target API	`{"url": "https://example.com"}`
`query_params`	Query-string parameters, by name	`{"limit": 10}`
`path_params`	Path parameters, by name	`{"crawlJobId": "abc123"}`
`headers`	Extra headers for the target API	`{"Accept": "text/csv"}`

All four fields are optional — send only what the operation’s schema requires. The operation always runs with its spec-defined HTTP method (a GET operation stays a GET), even though you call this endpoint with POST. The connection’s stored credentials are applied automatically, and the call times out after 300 seconds.

You can pass _ as the connector_id and it will be resolved from the connection: POST /v1/tools/connectors/_/connections/{connection_id}/{operation_id}

Common mistakes

❌ Doesn’t work	✅ Use instead
Using the connector page URL’s UUID as `connection_id`	That UUID is the `connector_id`; get `connection_id` from List Tools
`Authorization: Bearer <key>` with an API key	`x-api-key: <key>`
Putting the target API’s arguments at the top level of the body	Wrap them in `body_params` / `query_params` / `path_params`
`GET /v1/tools/search?query=...` without `type`	Always pass `type` as well, e.g. `?query=firecrawl&type=connector`

Invoke an Agent via API

Model Context Protocol

⌘I

Overview

REST API - Agents

REST API - Scheduled Tasks

REST API - Self-Schedules

Agent Workspace

REST API - Agent Gateway

REST API - Tasks

REST API - Knowledge

REST API - Workflows

REST API - Tools

REST API - Custom Functions

REST API - Misc

Invoke a Connector via API

Base URL & Authentication

The three IDs you need

Step 1 — Find the connector and its connection

Step 2 — List the operations

Step 3 (optional) — Inspect the operation’s inputs

Step 4 — Invoke

How the request body maps to the target API

Common mistakes

​Base URL & Authentication

​The three IDs you need

​Step 1 — Find the connector and its connection

​Step 2 — List the operations

​Step 3 (optional) — Inspect the operation’s inputs

​Step 4 — Invoke

​How the request body maps to the target API

​Common mistakes

Base URL & Authentication

The three IDs you need

Step 1 — Find the connector and its connection

Step 2 — List the operations

Step 3 (optional) — Inspect the operation’s inputs

Step 4 — Invoke

How the request body maps to the target API

Common mistakes