Call Tool

Call customer intelligence tools through the public tool gateway

POST /api/tools/call

Call Tool

cURL

curl --request POST \
  --url https://api.example.com/api/tools/call \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tool": "<string>",
  "input": {}
}
'

Endpoint

POST https://app.outlit.ai/api/tools/call

Authentication

Authorization · string · required

Outlit API key using the Bearer ok_... format.

Request Body

{
  "tool": "outlit_list_customers",
  "input": {
    "limit": 10,
    "billingStatus": "PAYING"
  }
}

tool · string · required

Customer intelligence tool name. Must be one of the supported tool names below.

input · object · default: "{}"

Tool-specific input object. The input is validated against the shared @outlit/tools contract before the tool runs.

Supported Tools

Tool	Purpose
outlit_list_customers	Browse and filter customers by billing status, activity recency, revenue, traits, or name
outlit_list_users	Browse and filter users by journey stage, activity recency, customer, traits, email, or name
outlit_get_customer	Get full details for one customer, with optional related sections
outlit_get_timeline	Get chronological customer activity across product, billing, support, and conversation channels
outlit_list_facts	Browse stored customer facts and evidence
outlit_get_fact	Retrieve one exact customer fact
outlit_get_source	Retrieve one exact source record behind a fact or search result
outlit_search_customer_context	Search customer context semantically
outlit_send_notification	Send a notification through the organization’s configured notifier; Slack is the default notifier
outlit_query	Run SQL against customer intelligence views
outlit_schema	Inspect available analytics views

Tool input schemas are published by @outlit/tools as customerToolContracts. Use that package when building schema-driven clients or model tool definitions.

outlit_send_notification is an action tool. Call it only when the user explicitly asks you to send, post, or notify a result. Prefer markdown for the human-readable body; payload can still carry JSON-serializable context. If destinations is omitted, Outlit uses the organization’s default notifier, currently Slack.

TypeScript Client

Use @outlit/tools when you want the same tool names and input contracts that power the CLI, Pi package, and public tool gateway:

npm install @outlit/tools

import { createOutlitClient, customerToolContracts } from "@outlit/tools"

const outlit = createOutlitClient({
  apiKey: process.env.OUTLIT_API_KEY!,
})

const result = await outlit.callTool(
  customerToolContracts.outlit_search_customer_context.toolName,
  {
    query: "What pricing concerns came up recently?",
    customer: "acme.com",
    sourceTypes: ["CALL", "EMAIL", "SUPPORT_TICKET", "OPPORTUNITY"],
    topK: 5,
  },
)

The package also exports customerToolContracts, defaultAgentToolNames, actionToolNames, sqlToolNames, allCustomerToolNames, and enum lists such as customerSourceTypes for schema-driven agent integrations. OPPORTUNITY is the canonical CRM opportunity source type; CRM and CRM_OPPORTUNITY are accepted input aliases. SDK helpers and CLI commands trim and normalize source type filters before calling the tool gateway.

Examples

List Paying Customers

curl -X POST https://app.outlit.ai/api/tools/call \
  -H "Authorization: Bearer ok_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "outlit_list_customers",
    "input": {
      "billingStatus": "PAYING",
      "limit": 10
    }
  }'

Get Customer Details

{
  "tool": "outlit_get_customer",
  "input": {
    "customer": "acme.com",
    "include": ["users", "revenue", "recentTimeline"],
    "timeframe": "30d"
  }
}

Search Customer Context

{
  "tool": "outlit_search_customer_context",
  "input": {
    "customer": "acme.com",
    "query": "What renewal concerns came up recently?",
    "sourceTypes": ["EMAIL", "CALL", "SUPPORT_TICKET", "OPPORTUNITY"],
    "after": "2026-01-01T00:00:00Z",
    "topK": 5
  }
}

List Active Facts From Calls And Opportunities

{
  "tool": "outlit_list_facts",
  "input": {
    "customer": "acme.com",
    "status": ["ACTIVE"],
    "sourceTypes": ["CALL", "OPPORTUNITY"],
    "after": "2026-01-01T00:00:00Z",
    "limit": 20
  }
}

Open One Source Record

{
  "tool": "outlit_get_source",
  "input": {
    "sourceType": "OPPORTUNITY",
    "sourceId": "opp_123"
  }
}

Send a Slack Notification

{
  "tool": "outlit_send_notification",
  "input": {
    "title": "Expansion signal",
    "severity": "high",
    "message": "Notify the channel after review.",
    "source": "pi-agent",
    "subject": "Acme expansion watchlist",
    "payload": {
      "customer": "acme.com",
      "reason": "High usage and plan-limit pressure",
      "signals": ["usage", "billing", "seat_growth"]
    }
  }
}

Response

The response is the selected tool’s JSON result. List tools return paginated collections; exact lookup tools return the matched record or an error when the record cannot be found. Search returns grouped artifact-level source and fact results, not raw vector chunks. Fact results include provenance fields such as sourceType, sourceId, sourceOccurredAt, sourceQuote, and permalink when available.

Example list response:

{
  "items": [
    {
      "id": "cus_123",
      "name": "Acme",
      "domain": "acme.com",
      "billingStatus": "PAYING",
      "mrrCents": 25000,
      "lastActivityAt": "2026-04-10T18:22:11.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cursor_abc",
    "total": 128
  }
}

Error Responses

Invalid JSON, unknown tool names, or invalid tool inputs return 400:

{
  "error": "Invalid tool input",
  "details": [
    {
      "path": ["limit"],
      "message": "Too big: expected number to be <=1000"
    }
  ]
}

Invalid credentials return 401. Plan API-call limits can return 402 or 429 with a stable billing code.