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)

Feedback to the Goliath team (WRITE scope)

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:

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

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.