> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask Goliath API

> Talk to a person's Ask Goliath agent from your own app or AI system, and send feedback to the Goliath team, through the developer API

## About

Every person in Goliath has **Ask Goliath**, an AI agent that knows their
account and works in it for them — searching contacts and properties,
building filters and workflows, updating deals, drafting messages. These
operations let your own app or AI system hold a conversation with it, as the
key's owner.

* **It acts as that person.** Anything it does, the key owner could do in the
  app, under the trust settings they chose there. When it needs a decision or
  an approval, it asks — and your app answers, exactly as the person's click
  would.
* **The chat is theirs.** A conversation you start shows in the person's own
  chat list, labelled with your key's name ("via *your app*"), and they can
  open it, read it and carry on in the app.
* **Same AI credits.** Replies spend the organization's AI credits, as chats
  in the app do.

The same domain carries `submitFeedback`: a bug report, feature request or
question from your app to the Goliath team.

All operations need a key with the **`WRITE`** scope — reading a turn
included, because a conversation can change data. All go through the
developer API gateway — one endpoint, called by `operationId`. If you haven't
set up a key yet, start with the [Developer API Overview](/developer-api/overview).

## Operations

### Conversations (`WRITE` scope)

| operationId | What it does |
| - | - |
| `startAgentConversation` | Start a new chat with its first `message`. Returns the turn (below). Waits up to `waitSeconds` (0–25, default 25) for the reply. |
| `sendAgentMessage` | Send a `message` in one of the person's chats (`conversationId`), as if they typed it. Returns the turn; waits like `startAgentConversation`. |
| `answerAgentQuestions` | Answer the questions the latest reply ended on — a question or an approval — as the person's click would. `answers` maps each question `id` to a label, a list of labels, free text, or `{ "other": "text" }`. Returns the turn; waits like `startAgentConversation`. |
| `getAgentTurn` | Read one message's turn by `conversationId` + `turnId`: its `status` and the `reply` so far. `waitSeconds` (0–25, default 0) holds until the reply finishes. |
| `cancelAgentTurn` | Stop the reply to one message. Changes it already made stay made. |
| `listAgentConversations` | The person's own chats, newest first — `id`, `title`, `archived`, `lastActivityAt`, and `appName` (the key that last talked in it). Page with `limit` (default 20) and `offset`; `archived: true` lists archived chats. |

### Feedback to the Goliath team (`WRITE` scope)

| operationId | What it does |
| - | - |
| `submitFeedback` | Send a `BUG` report, `FEATURE_REQUEST` or `QUESTION` as the key owner: a one-line `title` (up to 150 characters), the `message` (10–2,000 characters) and optional `details` (up to 2,900 characters). It lands on the Goliath team's board — added to your organization's open card for the same problem when there is one. Returns `status` (`FILED`, `ADDED` or `FAILED`), the `ticket` it wrote to (keep its name to refer to it later), and your organization's `otherOpenTickets`. At most 20 per hour per key. |

Input that breaks a limit is refused, never cut. Replies from the team are
not delivered through this API; they come back the way your organization
usually hears from us.

### The turn

Every conversation operation returns the same **turn** — one message you sent
and Ask Goliath's reply to it:

| Field | Meaning |
| - | - |
| `conversationId`, `turnId` | Where it is. Pass both to `getAgentTurn` and `cancelAgentTurn`. |
| `status` | `RUNNING` (still replying), `WAITING_FOR_CALLER` (it asked something: read `questions`), `COMPLETED`, `FAILED` (read `error`) or `CANCELLED`. |
| `reply` | The reply text so far. |
| `questions` | When `WAITING_FOR_CALLER`: each has an `id`, a `prompt`, a `kind`, its `options`, whether it is `multi`-select, and whether it `allowOther` free text. |
| `error` | Why a turn `FAILED` — for example, the organization is out of AI credits. |

> [!NOTE]
>
> **Replies take longer than one request**
>
> A call holds for at most 25 seconds. A reply still `RUNNING` then is not an
> error: poll `getAgentTurn` with `waitSeconds: 25` until the status changes.
> A long job can run for minutes, and the agent can carry on by itself after
> a reply; keep polling while the status is `RUNNING`.

> [!NOTE]
>
> **Approvals follow the person's trust settings**
>
> Where the person has told Goliath to ask first — before sending texts, for
> example — Ask Goliath stops with a question instead of acting.
> `answerAgentQuestions` approves or declines it exactly as their click would,
> so only answer what the person would have answered.

## TypeScript SDK

`askGoliath()` sends a message and polls until the reply is done, so one call
returns the finished turn:

```ts theme={null}
import { GoliathClient, askGoliath } from '@goliath-data/sdk'

const goliath = new GoliathClient({ apiKey: process.env.GOLIATH_API_KEY!, baseUrl: 'https://server.goliathdata.com' })

const turn = await askGoliath(goliath, { message: 'Which deals stalled this week?' })
console.log(turn.status, turn.reply)

// Carry on in the same chat.
await askGoliath(goliath, { conversationId: turn.conversationId, message: 'Draft a follow-up for the first one.' })
```

It gives up waiting after `timeoutMs` (default 10 minutes) and returns the
turn as it stands. The operations themselves are `goliath.askGoliath.*`.

> [!NOTE]
>
> `askGoliath()` and the `askGoliath` operations ship in the next SDK beta.
> Until then, call them by name with `goliath.execute(...)`, or over plain HTTP
> as below.

## Example

Start a chat, then poll for the reply:

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "operationId": "startAgentConversation", "variables": { "message": "How many new leads came in this week?" } }'
```

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "getAgentTurn", "variables": { "conversationId": "CONVERSATION_ID", "turnId": "TURN_ID", "waitSeconds": 25 } }'
```

Send feedback:

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "operationId": "submitFeedback", "variables": { "kind": "FEATURE_REQUEST", "title": "Webhook when a deal changes stage", "message": "We would like a push when any deal moves stage, instead of polling findDeals." } }'
```

Full variable schemas and response shapes for every operation are available
from the [discovery endpoint](/developer-api/overview#discovering-operations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.