Zapier, Make and n8n

Integration platforms connect Sursa to hundreds of other tools without code. They do not need a dedicated Sursa app: their generic HTTP request and webhook steps work with the API directly. This guide covers the three most common recipes:

Recipe	Direction	What you need
Push records from another tool into Sursa as cards	Into Sursa	A custom source and its `kbsrc_` key
Ask Sursa a question in a workflow	Into Sursa and back	An API key with the `ask` scope
Start a workflow when something happens in Sursa	Out of Sursa	A webhook pointing to the platform

Whichever platform you use, keep the key in its credentials or connection store, not in the step itself, so that it is not copied into every scenario and run log.

Push records as cards

Create a custom source in Sursa (Sources → New source → Custom source), then a key for it on the source page under API keys. The key starts with kbsrc_ and can only write documents into this source, which makes it the right key to store on a third-party platform.

The common setup is "when a record is created or updated in X, send it to Sursa":

Setting	Value
Method	`POST`
URL	`https://api.example.com/v1/push/sources/42/documents`
Header `Authorization`	`Bearer kbsrc_…`
Header `Content-Type`	`application/json`
Body	The JSON below, with fields mapped from the trigger

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

Map a stable ID of the record to external_id, never a time or a run number. Sending the same record again then updates the same card, and a retried step is harmless: the answer is unchanged.
For a "record deleted" trigger, add a second workflow with Method DELETE and URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
Test the connection with GET https://api.example.com/v1/push/sources/42 and the same Authorization header. It returns the name of the source and its number of documents.

The document fields are the same as for code.

Zapier

Use Webhooks by Zapier → Custom Request:

Method: POST.
URL: https://api.example.com/v1/push/sources/42/documents.
Data Pass-Through: off. Data: the JSON above, with fields inserted from the trigger.
Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Use the module HTTP → Make a request:

Method POST, URL as above, Headers Authorization: Bearer kbsrc_….
Body type Raw, Content type JSON (application/json), Request content: the JSON above with mapped values.
Turn on Parse response to use result (created, updated, unchanged) in later modules.
To send a file, choose Body type Multipart/form-data with a file field (the file from an earlier module) and a document text field that holds the JSON fields without content.

n8n

Use the node HTTP Request:

Method POST, URL as above.
Authentication Generic Credential Type → Header Auth, with name Authorization and value Bearer kbsrc_….
Send Body on, Body Content Type JSON, fields mapped with expressions such as {{ $json.id }}.

For a scheduled full export, chain three HTTP Request nodes: open a sync (POST …/syncs with {"type": "initial"} the first time, {"type": "incremental"} afterwards), push the items, and close the sync with {"status": "complete"}. n8n runs a node once per item; to send fewer requests, group the items with an Aggregate node and send them to …/documents/batch as {"sync_number": …, "documents": [...]}.

Ask a question in a workflow

A workflow can ask Sursa and use the answer: draft a reply to a support ticket, enrich a CRM record, post an answer in a chat channel. Use an organization API key with the ask scope and a role that sees the right collections.

Setting	Value
Method	`POST`
URL	`https://api.example.com/v1/ask`
Header `Authorization`	`Bearer kb_…`
Body	`{"query": "{{ticket_subject}}: {{ticket_body}}", "collection": "support"}`

The response has the answer in answer (Markdown) and its sources in sources, each with doc_name. When the knowledge base has nothing on the question, empty is set (for example no_hits): add a filter step so the workflow does not post an empty answer. See Build a Q&A bot.

Answers can take several seconds. If the platform's HTTP step has a short default timeout, raise it to at least 60 seconds.

Start a workflow from a Sursa event

Every platform can receive webhooks:

Platform	Trigger
Zapier	Webhooks by Zapier → Catch Raw Hook (raw, so the body stays as it was sent)
Make	Webhooks → Custom webhook
n8n	Webhook node, method `POST`

Create the trigger and copy the HTTPS address it gives you.
In Sursa, register a webhook with that address and the events you want, under Administration → Integrations → Webhooks and API or with POST /v1/webhooks.
Send a test event from the webhook page, and map the fields of the event (type, data.card.title, …) in the next steps.

Check the signature. The trigger address is public: anyone who learns it can send requests to it. Verify the signature of each delivery before acting on it, especially if the workflow changes data:

In n8n, add a Code node after the Webhook node with the Node.js verifier from Receive webhooks, and enable the raw body option of the Webhook node so that the exact bytes are available.
In Zapier and Make, where the raw body is harder to reach, at least keep the address secret, filter on type, and read the object again from the API before acting on it.

Retries and duplicates apply to platforms as to any receiver: filter on the id of the event if a duplicate run would be harmful.

Tips

On 429, let the platform's automatic retry wait for the Retry-After seconds. Prefer batches for large exports.
Platforms log every request and response. Never put a key in a URL, and prefer the kbsrc_ key wherever writing documents is all the workflow does.
If a step fails with 401 sources.push_key_invalid, check that the source ID in the URL matches the key.