Reference

Server client

createClient() and every method on it: who the token is, queries, numbers, kinds and records, saved queries, write recipes, the business, bookings, files, tasks, app people, Knowledge and the support desk.

The client for your server, a script or an n8n workflow, with the account's token or an app's server key. Both are secrets: never use them in a browser. Generated from the SDK's own code.

#createClient()

The server client: the account's token (amt_pat_... with crm:read) or an app's server key (ak_...). Both are secrets: keep them on a server, never in a browser.

createClient(options: ClientOptions): AwesomateClient

Example

const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
const { rows } = await db.query('contact', { limit: 10 });

#The token

#whoami()

Who this token is: the account, its plan, the token's scopes and when it expires, and which features the account has (each with the sentence to say when it does not), and whose key it is: the account owner's, which acts as the owner, or a team member's own, which does only what that person can do in the hub. Needs hosting:read; an app key cannot ask (it reads and writes its own kinds only).

db.whoami(): Promise<WhoAmI>

Example

const me = await db.whoami();
if (!me.features?.bookings?.available) console.log(me.features?.bookings?.message);

#Reading

#query()

Rows of one kind that this token can read, a page at a time. The account's token (crm:read, every plan, Contacts on the account) or an app key, for the kinds it was made for.

db.query<K, S>(kind: K, options?: QueryOptions<RowOf<K>, S>): Promise<Page<Pick<RowOf<K>, S>>>

Example

const { rows, next } = await db.query('contact', {
  where: { created_at: { gte: '$YEAR_BEGIN' } },
  orderBy: ['created_at', 'desc'],
  limit: 50,
});

#queryAll()

Every matching row, a page at a time. maxRows guards against reading a whole list by accident. Needs what query() needs.

db.queryAll<K, S>(
  kind: K,
  options?: Omit<QueryOptions<RowOf<K>, S>, "after"> & { maxRows?: number },
): AsyncGenerator<Pick<RowOf<K>, S>>

#get()

One row by id, or null when there is none this token can read. Ids are UUIDs: anything else names no row, so it answers null without asking the hub. Needs what query() needs.

db.get<K>(kind: K, id: string, options?: { tz?: string }): Promise<RowOf<K> | null>

#schema()

The kinds this token can read: each kind's columns with their types, operators, choices and the owner's descriptions and sections, how many fields are hidden and why, the query grammar and examples. Works with the account's token (crm:read, every plan, Contacts on the account) and with an app key (its own kinds, and access says whether it can write).

db.schema(): Promise<Schema>

#types()

The readable kinds as a TypeScript file (what the types command writes). The account's token, crm:read.

db.types(): Promise<{ as_at: string; content: string; file: string }>

#Numbers

#metrics()

What the contact list can be measured by: people (a count) and every number field the owner has named, each with its unit and other words for it. The catalogue for aggregate() and series(). The account's token, crm:read, every plan.

db.metrics(): Promise<Metric[]>

#series()

One metric over time, every bucket filled (a bucket nobody landed in is 0 for counts and sums): range is a preset (7d, 30d, 90d, 12m, mtd, qtd, ytd, fytd, this_month, last_month, this_fy, last_fy) or give from and to (YYYY-MM-DD); with neither, the last 12 months. compare: 'previous' adds the window before. At most 800 points. The account's token, crm:read, every plan.

db.series(
  metric: string,
  options?: { agg?: "sum" | "avg" | "min" | "max"; anchor?: string; compare?: "previous"; from?: string; grain?: "day" | "week" | "month" | "quarter" | "year" | "fy"; range?: string; to?: string; tz?: string },
): Promise<MetricSeries>

Example

const s = await db.series('people', { range: '90d', grain: 'week', compare: 'previous' });
console.log(s.total, s.compare?.delta_pct);

#datasets()

The contact list as a dataset: its columns by kind (measures, dimensions to group by, and the dates people can be counted by). The account's token, crm:read.

db.datasets(): Promise<Dataset[]>

#dataset()

One dataset by its id (contact), or null when there is none by that id. The account's token, crm:read.

db.dataset(id: string): Promise<Dataset | null>

#aggregate()

Grouped numbers (counts, sums) over the contact list, in the Business Data API's shape: the measures and dimensions datasets() lists. Counts and sums only, never a person. The account's token, crm:read, every plan; never an app key.

db.aggregate(
  request: { dimensions?: string[]; filters?: { column: string; op?: string; value: unknown }[]; limit?: number; measures: { agg?: "count" | "sum" | "avg" | "min" | "max"; column: string }[]; order_by?: { dir?: "asc" | "desc"; field: string }[]; time?: { anchor?: string; from?: string; grain?: string; preset?: string; to?: string; tz?: string } },
): Promise<Record<string, unknown>>

#Kinds and records

#kinds()

The app kinds this account has defined. The account's token, crm:read, every plan; never an app key.

db.kinds(): Promise<KindDescription[]>

#defineKind()

Define an app kind (a table an app keeps). No migration: registry rows and generated views. The account's token, crm:write, Support Plus and above; never an app key.

db.defineKind(spec: KindSpec): Promise<KindDescription>

#addAttribute()

Add an attribute to a kind you defined; records already there have no value for it. Answers the kind as it now is. The account's token, crm:write, Support Plus and above.

db.addAttribute(kind: string, attribute: AttributeSpec): Promise<KindDescription>

#archiveAttribute()

Archive an attribute: it leaves every read and the generated types, and its values are kept. Answers the kind as it now is. The account's token, crm:write, Support Plus and above.

db.archiveAttribute(kind: string, key: string): Promise<KindDescription>

#write()

Create a record (returns its id), or change one with options.id. Every value is checked against the kind. crm:write, Support Plus and above: the account's token, or an app key made with write access for this kind.

db.write<K>(
  kind: K,
  data: Record<string, unknown> | Partial<RowOf<K>>,
  options?: WriteOptions,
): Promise<string>

#archive()

Archive a record: it leaves every read and is kept for a restore. Needs what write() needs.

db.archive<K>(kind: K, id: string): Promise<void>

#Saved queries

#queries()

The saved queries on this account. crm:read, every plan: the account's token or an app key.

db.queries(): Promise<SavedQueryDescription[]>

#saveQuery()

Save a query by name (saving a name again replaces it). The spec is the query() grammar on one kind, with {"$param": ""} where a caller's value goes; it is compiled before it is stored, so a column it cannot read is refused now rather than when it runs. The account's token, crm:write, Support Plus and above; never an app key.

db.saveQuery(spec: SavedQuerySpec): Promise<SavedQueryDescription>

#run()

Run a saved query with its params. An optional param left out drops its condition. crm:read, every plan: the account's token or an app key.

db.run<Q>(
  query: Q,
  params?: ParamsOf<Q>,
  options?: { after?: string; limit?: number; tz?: string },
): Promise<Page<QueryRowOf<Q>>>

#archiveQuery()

Archive a saved query by its key. The account's token, crm:write, Support Plus and above.

db.archiveQuery(key: string): Promise<void>

#Write recipes

#recipes()

The write recipes on this account. crm:read, every plan: the account's token or an app key.

db.recipes(): Promise<RecipeDescription[]>

#saveRecipe()

Save a write recipe: up to 10 write_record / archive_record steps run in one transaction. {"$param": ""} takes a caller's value, {"$step": ""} the id an earlier step wrote. The account's token, crm:write, Support Plus and above; never an app key.

db.saveRecipe(spec: RecipeSpec): Promise<RecipeDescription>

#call()

Run a write recipe. Every step commits or none does; a refusal names the step and the field. Never retried: a write that may have landed is not safe to send twice. crm:write, Support Plus and above: the account's token, or an app key with write access to every kind it writes.

db.call<R>(recipe: R, args?: ArgsOf<R>): Promise<RecipeResult>

#archiveRecipe()

Archive a write recipe by its key. The account's token, crm:write, Support Plus and above.

db.archiveRecipe(key: string): Promise<void>

#The business

#business()

The business itself: the details Awesomate keeps about it (name, what it does, voice, colours, how customers reach it), grouped, each with where it came from. confirmed details are the ones agents and automations use; suggestion ones wait for the owner. Needs the account's token (hosting:read, every plan), never an app key.

db.business(): Promise<BusinessIdentity>

#businessCatalogue()

Every detail a business can have (key, label, group, type and longest value), set or not, for a page that offers the missing ones. No values: business() has those. The account's token, hosting:read, every plan.

db.businessCatalogue(): Promise<BusinessCatalogue>

#businessSuggestions()

Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. The account's token, hosting:read, every plan.

db.businessSuggestions(): Promise<BusinessSuggestion[]>

#businessDocuments()

The business's long documents that exist (brand guide, voice guide, brand from the website, business summary): kind, version, length and where each came from, without the text. Needs the account's token (hosting:read, every plan), never an app key.

db.businessDocuments(): Promise<BusinessDocumentSummary[]>

#businessDocument()

One of the business's documents with its text (the current version), or null when the business has none of that kind yet. The text is the owner's own: use it for their business (agent instructions, site copy in their voice), never show it to anyone else. The account's token, hosting:read, every plan.

db.businessDocument(kind: BusinessDocumentKind): Promise<BusinessDocument | null>

#businessMap()

The business map: the seven departments every business has, their sub-departments, the roles in each and who holds them, which agents and automations help which role and how far each may go, and what is missing, most important first. Read only: the owner changes the map in the hub. Needs the account's token (hosting:read, every plan), never an app key, and the account must have the business map. Since 0.24.0 in the words the owner sees; businessMapV1() is the old shape.

db.businessMap(): Promise<BusinessMap>

#businessMapRoles()

Every role on the map, one line each: slug, title, department and who holds it. hosting:read, the business map on the account.

db.businessMapRoles(): Promise<BusinessMapRoleSummary[]>

#businessMapRole()

One role by its slug, with the line each helper's instructions carry (helpers[].instructionLine): which role it helps, for whom, how far it may go and where its procedures are. hosting:read, the business map on the account.

db.businessMapRole(slug: string): Promise<BusinessMapRoleDetail>

#businessMapV1()

The business map in its first shape, where a department is a division, a sub-department a department and a role a job. hosting:read, the business map on the account.

db.businessMapV1(): Promise<BusinessMapV1>

#Email series

#recordEvent()

Tell Contacts something happened to someone ("job_paid", "quote_sent"), so any email series waiting for that event starts or stops for them. The person is found by email, or added; it never signs anyone up for email or changes their consent. Sending the same key twice records the event once (duplicate: true), so pass your own id for it. record names the quote, job or booking it is about. An event more than two days old is kept as a fact a series reads, never a start. Needs the account's token with crm:write (Support Plus and above), never an app key. The answer is the same whether or not the address belongs to someone erased from Contacts.

db.recordEvent(event: SeriesEvent): Promise<{ duplicate: boolean }>

Example

await db.recordEvent({ event: 'job_paid', email: 'sam@example.com', record: 'job-1042', key: 'xero:INV-1042' });

#Bookings

#bookings.setup()

How bookings are set up: whether they are on, the calendars (people, rooms) with their hours, the services with the calendars that take them, and this month's online bookings against the plan's. The keys here are what openTimes() and book() take. crm:read.

db.bookings.setup(): Promise<BookingSetup>

#bookings.list()

Bookings that start in a window, soonest first, each with its customer. The window is from a day ago for 31 days unless told otherwise; limit is 1 to 500 (default 200).

db.bookings.list(
  options?: { calendar?: string; from?: string | Date; limit?: number; status?: "cancelled" | "confirmed" | "completed" | "no_show"; to?: string | Date },
): Promise<StaffBooking[]>

#bookings.get()

One booking by its id, or null when there is none (an id that is not a booking id never reaches the hub).

db.bookings.get(id: string): Promise<StaffBooking | null>

#bookings.openTimes()

The times a service can be booked, from now for two weeks unless told otherwise (at most 62 days at once). The same open times customers see; book() with outsideHours goes beyond them.

db.bookings.openTimes(
  service: string,
  options?: { calendar?: string; from?: string | Date; seats?: number; to?: string | Date },
): Promise<OpenTime[]>

#bookings.book()

Book a time for a customer named by email (found in Contacts, or added; consent is never changed). Switches Bookings on if it was not. A time that is not open is refused with code conflict and field saying why: not_open, slot_taken, too_many_seats, session_full or day_full. Pass idempotencyKey so a retry returns the same booking.

db.bookings.book(
  request: StaffBookingRequest,
): Promise<{ bookingId: string; created: boolean; endsAt: string; startsAt: string }>

#bookings.cancel()

Cancel a booking. A booking already cancelled answers cancelled: false.

db.bookings.cancel(
  id: string,
  options?: { notify?: boolean; reason?: string },
): Promise<{ bookingId: string; cancelled: boolean; status: string | null }>

#bookings.move()

Move a confirmed booking to a new start, on the same calendar or another (calendar). A time that is not open is refused with code conflict (field not_open, slot_taken, session_full or day_full) unless outsideHours; a booking that is not confirmed, or a time that has passed, with code validation.

db.bookings.move(
  id: string,
  startsAt: string | Date,
  options?: { calendar?: string; notify?: boolean; outsideHours?: boolean },
): Promise<{ bookingId: string; calendar: string; endsAt: string; startsAt: string }>

#bookings.outcome()

Record how a booking went: the customer came (completed) or did not (no_show). Sends no email.

db.bookings.outcome(id: string, status: "completed" | "no_show"): Promise<void>

#Files

#files.list()

One folder; '' (the default) lists the top folders.

db.files.list(path?: string): Promise<FileEntry[]>

#files.search()

Files by part of their name (* and ? are wildcards), across the folders or in one. At most 200: truncated says there were more.

db.files.search(
  options?: { extensions?: string[]; q?: string; top?: "public" | "private" | "temp" },
): Promise<{ results: FileEntry[]; truncated: boolean }>

#files.usage()

Space used against the plan's Files space. Measured, and up to ten minutes old.

db.files.usage(): Promise<FilesUsage>

#files.upload()

Write a file (up to 50 MB). Refuses to replace one already there unless overwrite. A full Files space answers serverCode files_storage_full.

db.files.upload(path: string, data: FileBody, options?: { overwrite?: boolean }): Promise<FileEntry>

#files.download()

A file's contents.

db.files.download(path: string): Promise<Blob>

#files.mkdir()

Make a folder, and any above it.

db.files.mkdir(path: string): Promise<FileEntry>

#files.move()

Move or rename. Anything using the old path or address needs the new one.

db.files.move(from: string, to: string): Promise<FileEntry>

#files.makePublic()

Move a file from private/ or temp/ to the same place under public/, and answer its public_url. Anyone with the address can open it.

db.files.makePublic(path: string): Promise<FileEntry>

#files.makePrivate()

Move a file out of public/ into private/. Its public address stops serving it within seconds (a browser that already opened it may keep its own copy for a while).

db.files.makePrivate(path: string): Promise<FileEntry>

#files.remove()

Move to the trash. Not erased, and no longer counted toward the Files space.

db.files.remove(path: string): Promise<{ trashPath: string }>

#files.trash()

What is in the trash, and how many bytes it holds. Needs files:read.

db.files.trash(): Promise<{ entries: TrashEntry[]; total_bytes: number }>

#files.emptyTrash()

Erase what is in the trash, for good: the only call that deletes a file outright. With olderThanDays (1 to 3650), only what was removed longer ago than that. Needs files:write. An automation account that cannot empty its trash yet answers serverCode trash_empty_unavailable.

db.files.emptyTrash(
  options?: { olderThanDays?: number },
): Promise<{ bytes: number; files: number; removed: number }>

#files.extract()

Unpack a .zip in Files into a folder beside it, named after the archive (skills.zip unpacks to skills/). At most 4,000 entries and 250 MB unpacked. Needs files:write.

db.files.extract(path: string): Promise<{ extractedTo: string; fileCount: number }>

#files.capabilities()

Whether Files works for this account now, and why not: the plan, the automation account's version, and the owner's privacy switch, with the largest upload and the plan's space. Works with any account token, so check it before offering Files.

db.files.capabilities(): Promise<FilesCapabilities>

#Tasks

#tasks.board()

The board: waiting now, put off, with someone else, recently decided. all shows everyone's, not only yours. hosting:read.

db.tasks.board(options?: { scope?: "mine" | "all" }): Promise<TaskBoard>

#tasks.give()

Give a task. The person gets it on their board, and an email when they are not the one giving it. hosting:manage.

db.tasks.give(
  task: GiveTask,
): Promise<{ emailed: boolean; holder: TaskPerson; id: number; key: string }>

#tasks.update()

Change a given task: whoever wrote it, or the owner. hosting:manage.

db.tasks.update(id: string | number, patch: Partial<Omit<GiveTask, "forEmail">>): Promise<void>

#tasks.done()

Mark a given task done: the person who has it, whoever wrote it, or the owner. hosting:manage.

db.tasks.done(id: string | number): Promise<void>

#tasks.drop()

Take a given task off the board without doing it: whoever wrote it, or the owner. hosting:manage.

db.tasks.drop(id: string | number): Promise<void>

#tasks.bringBack()

Open a done or dropped task again, with the person who had it. They get an email unless they are the one bringing it back. Who may: see decided[].canBringBack on the board. hosting:manage.

db.tasks.bringBack(id: string | number): Promise<{ emailed: boolean }>

#tasks.record()

What happened to a given task, in order: who gave it, who passed it on, who closed it and brought it back, and how long each person had it. The owner reads any task's record; anyone else only one they were part of. hosting:read.

db.tasks.record(id: string | number): Promise<TaskRecord & { kind: "task" }>

#tasks.notNow()

Put a card off until a time (at most 90 days), for this person only. hosting:manage.

db.tasks.notNow(key: string, until: string | Date): Promise<{ until: string }>

#tasks.cancelNotNow()

Bring a card put off with notNow() back now, for this person. hosting:manage.

db.tasks.cancelNotNow(key: string): Promise<void>

#tasks.passOn()

Hand a card to someone on the account who can act on it. hosting:manage.

db.tasks.passOn(
  key: string,
  toEmail: string,
  reason?: string,
): Promise<{ emailed: boolean; holder: TaskPerson }>

#tasks.decisions()

The decisions on the Tasks page: waiting now, put off, said yes to and gone further up, and decided in the last 14 days. A token is no one person, so mine shows only decisions waiting on the owners; pass scope: 'all' for the rest, including what was decided. Read only: deciding is a person's tap in the hub, never a token's, so every card's actions is empty here. hosting:read; refused with serverCode not_live where decisions are not switched on yet.

db.tasks.decisions(options?: { scope?: "mine" | "all" }): Promise<DecisionBoard>

#tasks.decisionRecord()

What happened to a decision, in order, with how long each person had it. A decision this token may not see reads as not found (serverCode gone). hosting:read.

db.tasks.decisionRecord(taskId: string | number): Promise<TaskRecord & { kind: "decision" }>

#App people

#appUsers.list()

Everyone who can sign in, newest first (at most 1,000), with their role, last sign-in and whether they are disabled.

db.appUsers.list(): Promise<AppPerson[]>

#appUsers.invite()

Let someone sign in, with a role (default member); a person already on the list keeps their id and takes the new role. No email is sent: they sign in from your app with auth.signInWithLink(). They are linked to the contact in Contacts with the same email.

db.appUsers.invite(email: string, options?: { role?: string }): Promise<AppPerson>

#appUsers.update()

Change someone's role, disable or enable them, or link them to a contact (contactId, or null to unlink). Disabling ends every session they have at once; sessionsRevoked says how many. A role is lower case: letters, digits and _.

db.appUsers.update(
  id: string,
  patch: { contactId?: string | null; disabled?: boolean; role?: string },
): Promise<{ sessionsRevoked: number; user: AppPerson }>

#assistantUsage()

One app's AI assistant this month (UTC): how many conversations it looked at, replied to or drafted for, how many replies asked Knowledge (those count towards Knowledge answers), and the AI tokens, with how many were on the account's own AI key. The account's token, crm:read.

db.assistantUsage(appId: string): Promise<AssistantUsage>

#Knowledge

#knowledge.ask()

A cited answer from the account's own content. grounded is true only when the answer came with sources: an answer with none came from the model, not the content, so never present it as the business's. session keeps a conversation going.

db.knowledge.ask(
  question: string,
  options?: { filters?: KnowledgeFilters; session?: string },
): Promise<KnowledgeAnswer>

#knowledge.search()

Instant search over the library: hits with highlighted snippets and facet counts for the current filters. A facet given several values matches any of them. Snippets mark the matched words between highlight.pre and highlight.post. limit is 1 to 50.

db.knowledge.search(options?: KnowledgeSearchOptions): Promise<KnowledgeSearchResult>

#knowledge.data()

Grouped numbers from Your numbers: a dataset by its id (the Data tab lists them; built-in ones are ds-builtin-<slug>, such as ds-builtin-google-analytics-daily), one to eight measures, and optional dimensions, filters and time. The answer is the platform's own shape: columns and rows, plus what it assumed.

db.knowledge.data(query: KnowledgeDataQuery): Promise<Record<string, unknown>>

#Support desk

#supportDesk.status()

Whether the desk is on, the address mail is forwarded to, how its AI answers, and how many tickets are in each status.

db.supportDesk.status(): Promise<SupportDeskStatus>

#supportDesk.tickets()

Tickets in one status (default open, or all), most recent first; limit 1 to 100 (default 25).

db.supportDesk.tickets(
  options?: { limit?: number; status?: "all" | SupportTicketStatus },
): Promise<{ counts: Record<SupportTicketStatus, number>; tickets: SupportTicketSummary[] }>

#supportDesk.ticket()

One ticket with its messages, the team's notes and any reply waiting for a person's OK, or null when there is none (an id that is not a ticket id never reaches the hub).

db.supportDesk.ticket(id: string): Promise<SupportTicket | null>