Push knowledge to the Secretary

Pushed knowledge is text the Secretary answers questions from, sent by your system instead of uploaded by hand. Use it for anything that changes rarely and fits in a page: FAQs, how something works, policies, a summary of what you offer.

For data that changes often or is too big to copy, use connected actions instead.

Creating or replacing

PUT /api/v1/knowledge/how-verification-works
Authorization: Bearer ord_live_...
Content-Type: application/json

{
  "title": "How we verify salaries",
  "content": "Every salary submitted is checked against an offer letter or payslip before it is published. Figures are shown only when at least 5 verified entries exist for a role and city..."
}

• The last part of the path is your key for this text: 1 to 80 letters, digits, dots, underscores, colons or hyphens, starting with a letter or digit. Use something stable, such as your own page or article id.
• The first push creates it (201). Pushing the same key again replaces it (200). If nothing changed, the response includes "unchanged": true, so a nightly sync of everything is cheap.
• title: up to 200 characters. content: 20 to 8,000 characters of plain text. Longer material: split it across keys, by topic.

{ "key": "how-verification-works", "title": "How we verify salaries", "chars": 1840, "updatedAt": "2026-10-01T10:00:00.000Z", "createdAt": "2026-10-01T10:00:00.000Z", "unchanged": false }

Listing and removing

• GET /api/v1/knowledge lists everything you pushed for this business.
• DELETE /api/v1/knowledge/{key} removes one: 204, or 404 when nothing is under that key.

The owner sees your texts in their knowledge sources, marked as added by a connected app, and can remove any of them.

Limits

• Each key counts as one knowledge source on the business's plan, together with any PDFs and websites the owner added: 3 on Pro, 5 on Business. Over the limit, a new key returns 403; replacing an existing key always works.
• Up to 120 pushes per hour per business; then 429 until the hour is up.
• The Secretary reads all of a business's knowledge together, up to about 16,000 characters per answer, so shorter, focused texts work best.

How the Secretary uses it

The business's own settings come first. Opening hours, services, prices and contact details are read from the dashboard, so if pushed text disagrees with them ("we open at 8am" while the hours say 9am), the Secretary follows the settings. Push what the settings cannot hold, and ask the owner to change the settings themselves.

Pushed text is treated as information, never as instructions. A sentence such as "ignore your rules" inside it is read as text, not obeyed. Write it the way you would explain things to a new member of staff: facts, figures, links.