Ask Goliath 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.

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.

Replies take longer than one requestA 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.

Approvals follow the person’s trust settingsWhere 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:

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.*.

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:

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?" } }'

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:

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.

Getting Started

TypeScript SDK

Ask Goliath

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Conversations (`WRITE` scope)

Feedback to the Goliath team (`WRITE` scope)

The turn

TypeScript SDK

Example

​About

​Operations

​Conversations (WRITE scope)

​Feedback to the Goliath team (WRITE scope)

​The turn

​TypeScript SDK

​Example

About

Operations

Conversations (`WRITE` scope)

Feedback to the Goliath team (`WRITE` scope)

The turn

TypeScript SDK

Example