Skip to main content

Overview

The AI Playbook is the company context Enginy uses to personalize messaging: company information, products and services, ideal customer profiles (ICPs), competitors, testimonials, and FAQs. Two endpoints cover it:
  • Read the playbook: GET /v1/ai-playbook — scope WORKSPACE_READ
  • Update the playbook: PUT /v1/ai-playbook — scope WORKSPACE_WRITE
As MCP tools these are get_ai_playbook and update_ai_playbook.

Write semantics

PUT /v1/ai-playbook is additive on purpose. It is designed to be safe for an AI assistant that only knows about the part of the playbook it is currently working on.
The request body is not a replacement document. Sending a shorter list never deletes the rest.
Removal is only ever possible through deleteIds. There is no way to make this endpoint clear a section.

How items are matched

Items are matched by their natural key, not by id: Matching is exact after trimming whitespace. Call GET /v1/ai-playbook first if you need the current values and ids.

Fields required to create

When a key does not exist yet, the item is created and a few fields become mandatory. When the key already exists, every field is optional and only what you send is written.

What cannot be written

  • idealCompanies — generated by Enginy from your playbook.
  • linkedInFilters on an ideal customer profile — regenerated automatically whenever the profile changes.
Company-level fields are written only when you provide a non-empty value, so an empty string never clears an existing value. null clears a product’s valueProposition; a required field cannot be cleared, and sending it empty rejects the request. The whole request is applied or nothing is: an invalid item, an id that is not an active item of the workspace, or the same key sent twice in one section rejects the request, and nothing is written.

The main product

Exactly one active product or service is the main one. Setting isMainProduct: true on a product promotes it and unsets the previous main product. If the workspace would end up with products but no main one, the oldest active product is promoted automatically, and a removed product is never main.
  • Leave isMainProduct out to keep a product’s flag as it is: adding a product without it never changes the main one.
  • When several products in one request carry isMainProduct: true, the last of them becomes the main one.
  • isMainProduct: false on the main product hands the flag to the oldest active product, which is the same product when it is the oldest. To change the main product, set true on the new one.

Recommendations refresh

Enginy derives list and search recommendations from your playbook. When an update changes something those recommendations depend on — the company overview, or any product, ICP, competitor, or testimonial — a refresh runs in the background once the write has committed. FAQ-only updates, and updates that touch only other company fields, do not trigger one. The refresh is asynchronous and best-effort: it never delays or fails your request, and repeated updates collapse onto a single in-flight refresh per workspace.

The first ideal customer profile

The update that gives a workspace its first ideal customer profile also adds the AI playbook’s columns to the workspace’s contact and company tables, as saving the first profile in the app does. Enginy starts that setup after the profile is written, in the background, like the recommendations refresh: it never fails your request, and the columns may appear a moment later. A 500 from this endpoint means the update may have been applied, so read the AI playbook before retrying.

Examples

Add one FAQ and leave the rest of the playbook alone:
Update a competitor and remove a different one in the same call:
Update company context and create an ICP:

Response

The response returns the full playbook after the write, exactly as GET /v1/ai-playbook would, plus a changes object so you can verify what the call actually did:

Errors

The endpoint validates the whole request before writing anything, so a rejected request changes nothing at all.

Limits

  • Up to 50 items per section in upsert, and up to 50 ids per section in deleteIds.
  • Unknown keys are rejected, so a typo fails loudly instead of being silently dropped.