Developer API Overview

About

The Goliath developer API lets your own code — servers, scripts, AI agents, or third-party tools — read and write the same data you work with in the app: contacts, properties, deals and pipelines, workflow automations, forms, and team settings.

There is one HTTP endpoint. You never send GraphQL or build queries — instead you call a named operation from a fixed catalog (an operationId) with its variables, and Goliath executes a pre-authored, pre-reviewed request on your behalf. Every call runs as the key’s owning user, so your real organization permissions and visibility apply — the API can never see or touch anything you couldn’t see in the app yourself.

Generating an API key

1. Open API Keys. From the app, go to Settings → API Keys (also reachable from the API Keys card on the Integrations page). Independent-operator seats cannot create API keys.

2. Create a key. Keys are personal — each key belongs to your user and acts as you. Create one key per host or device so you can revoke them independently.

3. Pick scopes. Each key carries one or more scopes (see below). ADMIN can only be granted to a key whose owner is a team admin.

4. Store the secret. The key looks like gsk_.... Pass it as a Bearer token on every request and keep it in your secrets manager — never ship it in a browser, mobile app, or any client-side code.

Scopes

Scopes decide what kind of operation a key may run. Which specific records it may touch is a separate check — see Authorization for how organization ownership and the two kinds of 403 work.

Making a request

POST https://server.goliathdata.com/api/v1/call
Authorization: Bearer gsk_...
Content-Type: application/json

{ "operationId": "getContact", "variables": { "contactId": "..." } }

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "findContacts", "variables": { "searchTerm": "smith" } }'

(POST /api/v1/graphql is the same endpoint under its original name and stays supported — despite that path, it does not accept GraphQL queries either.)

A handled request always returns 200 with a GraphQL-style body:

{ "data": { ... }, "errors": [ ... ] }

Transport, authorization, and subscription problems use HTTP status codes instead:

Result limits & truncation

Capped list/search operations declare a result cap — a maximum number of rows requested per call. If you send a limit larger than the cap, the gateway silently clamps it before execution: the operation runs with the capped limit and returns up to that many rows, without a limit error. The gateway does not trim the response after execution.

Most list operations are fully pageable — they take an offset (or a cursor) and return a totalCount and/or hasMore, so you can walk the whole result set a page at a time. Prefer these when you need everything:

# page through all matches
{ "operationId": "findContacts", "variables": { "searchTerm": "smith", "limit": 50, "offset": 0 } }
{ "operationId": "findContacts", "variables": { "searchTerm": "smith", "limit": 50, "offset": 50 } }

listAppointments and listMyTasks support forward cursor pagination (default 25, cap 50). When canFetchNext is true, keep the same filters and set cursor to the last returned row’s id. Repeat until false; restart without a cursor to revisit earlier rows. Their total is the unpaged match count.

Discovering operations

The full operation catalog is machine-readable — ideal for AI agents and for keeping your integration in sync:

GET https://server.goliathdata.com/api/v1/operations
Authorization: Bearer gsk_...
→ 200 { "operations": [{ "operationId", "operationType", "requiredScope", "summary", "authorized" }] }

GET https://server.goliathdata.com/api/v1/operations/:operationId
→ 200 { variables, responseShape, example, notes, ... }

• The list returns one-line summaries of every operation.
• The detail view returns the full variable schema, the exact response shape, and a copy-pasteable example for one operation.
• authorized reflects your key’s scopes, so a caller sees exactly what it is allowed to run.

Operations behind an organization feature gate are omitted when unavailable to your key. Their detail endpoint returns 404 unknown_operation, and calling their id returns 400 unknown_operation.

Operation reference by area

The catalog is documented alongside each feature’s user guides:

• Properties API — search properties, count signal events, author CONTACT/PROPERTY/DEAL filters, manage filter folders, and organize lists
• Contacts API — read, create, update, and enrich contacts, find duplicate groups, and manage contact filters
• Deals API — search and filter deals, read open-task counts, edit custom fields, and manage Scraper Health cards
• Pipelines API — manage pipeline structure and read pipeline analytics
• Workflows API — manage automations and runs across contact, deal, property, appointment, and event domains; set live sending schedules, bulk-enroll contacts, restore archived workflows, and apply task templates and sets
• Content Templates API — manage message, task, and task-set templates and folders
• Forms API — manage lead-capture forms and read form analytics
• Communications API — read and triage inbox threads, read recordings and transcripts, manage suppressions, and render templates
• Notifications API — read your notification feed and mark items read
• Appointments API — check live calendar conflicts, schedule appointments, manage SMS reminders, and configure availability
• Tasks API — create, reschedule, and complete CRM to-do tasks
• Skip Trace API — run skip traces from your own systems
• Bulk Tasks API — poll the status of long-running bulk jobs
• Team API — roster, role and permission changes, teams, goal plans, member suspension/restoration, invitations, live activity counts, and nightly analytics
• Account API — your profile, organization settings, intake assignment, permissions, integration status and disconnection, and setup links
• Billing API — subscription dates, plan allowances, AI usage warnings, credit balances and usage, and fixed credit packs
• AI Employees API — create, configure, and supervise AI employees
• Automation Map API — read and edit the Automations Map
• Scheduled Tasks API — recurring Ask Goliath tasks
• Contracts API — draft, send, and track contracts for signature
• Call Lists API — build and work call lists
• Contact Imports API — map, preview, and import a contact spreadsheet
• Files API — exports, skip-trace runs, and upload reports
• Library API — the Library’s spaces, files, and file runs
• Memory API — what Goliath remembers about your business
• Coverage API — data coverage for your markets
• Partnerships API — lead-sharing partnerships with other organizations

Capabilities managed in the app

Use the app for capabilities outside the public operation catalog:

• File uploads — a spreadsheet enters Goliath through the app or an Ask Goliath chat; from there the Contact Imports API and the Library API take over.
• Buying credits and changing the plan — a person does it in the app; see the Billing API.

Texts, emails, and contract sends are available to the API once an org admin makes the send consent attestation.