Getting Started

5-Minute Quickstart

List your integrations, pick a verified one, resolve its tools and invoke a tool from Python or TypeScript.

This guide calls the API directly with requests and fetch, so it runs without installing anything else. The same flow with the typed SDKs is in the Python and TypeScript client guides.

Before you start you need:

An integration connected in the dashboard with credentials verified. See Managed Authentication.
An access token in DF_TOKEN. See Get an access token.

The worked example uses a DeepSeek connection and its deepseek_list_models tool, which is read-only and takes no arguments. Substitute a tool slug and arguments from your own integration in Step 4.

The TypeScript blocks use top-level await: save them as an ES module, for example quickstart.mjs.

Step 1: Configure the Client

import os

import requests

base_url = os.getenv("DATAFUSE_API_URL", "https://api.datafuse.xyz")
headers = {"Authorization": f"Bearer {os.environ['DF_TOKEN']}"}

const baseUrl = process.env.DATAFUSE_API_URL || 'https://api.datafuse.xyz'
const headers = { Authorization: `Bearer ${process.env.DF_TOKEN}` }

async function call(path, init = {}) {
  const response = await fetch(baseUrl + path, { ...init, headers: { ...headers, ...init.headers } })
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`)
  return response.json()
}

Step 2: Pick a Verified Integration

Every integration reports whether its credentials have been verified. Only verified integrations expose tool schemas and run tools.

response = requests.get(f"{base_url}/api/v1/integrations", headers=headers)
response.raise_for_status()

verified = [item for item in response.json()["items"] if item["verified"]]
if not verified:
    raise SystemExit("No verified integration. Connect and verify one in the dashboard first.")

integration_id = verified[0]["id"]
print(f"Using {verified[0]['provider_key']} integration {integration_id}")

const integrations = await call('/api/v1/integrations')

const verified = integrations.items.filter((item) => item.verified)
if (verified.length === 0) {
  throw new Error('No verified integration. Connect and verify one in the dashboard first.')
}

const integrationId = verified[0].id
console.log(`Using ${verified[0].provider_key} integration ${integrationId}`)

!NOTE If you have several verified integrations, choose the one you want by its provider_key instead of taking the first.

Step 3: Resolve Tools

Resolving returns each tool's slug, description and input_schema. The slug is what you pass to invoke.

response = requests.post(
    f"{base_url}/api/v1/integrations/{integration_id}/resolve-tools",
    headers=headers,
)
response.raise_for_status()
tools = response.json()

for tool in tools:
    required = tool["input_schema"].get("required", [])
    print(f"{tool['slug']}  required arguments: {required}")

const tools = await call(`/api/v1/integrations/${integrationId}/resolve-tools`, { method: 'POST' })

for (const tool of tools) {
  const required = tool.input_schema.required ?? []
  console.log(`${tool.slug}  required arguments: ${JSON.stringify(required)}`)
}

!IMPORTANT A 403 with connection_verification_required means the integration's credentials have not been verified. Re-enter working credentials in the dashboard, or call POST /api/v1/integrations/{id}/test and check that the response has "verified": true.

Step 4: Invoke a Tool

Send the tool's slug as tool_key, and arguments that match its input_schema. Each invoke counts as one tool call on your plan.

response = requests.post(
    f"{base_url}/api/v1/integrations/{integration_id}/invoke",
    headers=headers,
    json={"tool_key": "deepseek_list_models", "arguments": {}},
)
response.raise_for_status()
result = response.json()

print(result["successful"])
print(result["data"] if result["successful"] else result["error"])

const result = await call(`/api/v1/integrations/${integrationId}/invoke`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tool_key: 'deepseek_list_models', arguments: {} })
})

console.log(result.successful)
console.log(result.successful ? result.data : result.error)

The HTTP status is 200 whenever Datafuse accepted the call. Check successful: when the provider rejects the request, successful is false and error says why. An unknown tool_key returns 404.

Running Tools with an API Key

Steps 3 and 4 also accept an API key, so an agent in production does not need a short-lived access token. Send x-api-key instead of Authorization:

headers = {"x-api-key": os.environ["DATAFUSE_API_KEY"]}

Listing integrations (Step 2) still needs an access token, so look the integration id up once and store it with your agent's configuration.

Next Steps

Run the same flow from the terminal with the curl quickstart.
Hand the tools to a model with tool schemas for any framework.
Skip the HTTP calls entirely and connect an MCP client.

Installation Guide

Install the Datafuse SDK for Python or TypeScript and set up the two credentials the API uses.

5-Minute Quickstart with curl

Run the Datafuse v1 flow from the terminal with curl and jq.