> ## Documentation Index
> Fetch the complete documentation index at: https://outlit-codex-platform-actions-create-update-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Tool

> Call customer intelligence tools through the public tool gateway

## Endpoint

```http theme={null}
POST https://app.outlit.ai/api/tools/call
```

## Authentication

<ParamField header="Authorization" type="string" required>
  Outlit API key using the `Bearer ok_...` format.
</ParamField>

## Request Body

```json theme={null}
{
  "tool": "outlit_list_customers",
  "input": {
    "limit": 10,
    "billingStatus": "PAYING"
  }
}
```

<ParamField body="tool" type="string" required>
  Customer intelligence tool name. Must be one of the supported tool names below.
</ParamField>

<ParamField body="input" type="object" default="{}">
  Tool-specific input object. The input is validated against the shared `@outlit/tools` contract before the tool runs.
</ParamField>

## 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_list_workspace_users`    | Browse internal workspace users such as CSMs, managers, account owners, and admins                     |
| `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_list_sources`            | List concrete source records such as calls, emails, calendar events, support tickets, or opportunities |
| `outlit_search_customer_context` | Search customer context semantically                                                                   |
| `outlit_query`                   | Run SQL against customer intelligence views                                                            |
| `outlit_schema`                  | Inspect available analytics views                                                                      |
| `outlit_send_notification`       | Send a notification through the organization's configured notifier; Slack is the default notifier      |

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

<Note>
  `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.
</Note>

## 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:

```bash theme={null}
npm install @outlit/tools
```

```typescript theme={null}
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

```bash theme={null}
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

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

### Search Customer Context

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "tool": "outlit_get_source",
  "input": {
    "sourceType": "OPPORTUNITY",
    "sourceId": "opp_123"
  }
}
```

### Send a Slack Notification

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`.