Agent triggers

Create a trigger

Open a project in the Kognita dashboard and go to Triggers. Create a trigger with a name, model settings, and a system prompt. The system prompt should tell the agent what kind of work to do and where to deliver the result, because the HTTP caller does not wait for the full agent run.

• Use one trigger per external workflow when you want separate credentials, prompts, or audit history.
• Write the prompt for the delivery channel, such as "comment on the Jira issue" or "send the summary through the connected tool".
• Keep the trigger token private. Rotate by deleting and recreating the trigger if the credential leaks.

POST request format

Each trigger card shows the exact invocation URL and required headers. The public URL normally ends with/triggers/invoke.

POST https://agent.kognita.co/triggers/invoke
Content-Type: application/json
X-Kognita-Auth: <trigger-auth-token>
X-Organisation-Id: <organization-uuid>
X-Project-Id: <project-uuid>

For simple integrations, send a JSON body with a message field. Kognita also accepts prompt ortext. If the body is a native webhook payload, the gateway passes the serialized payload through so the agent can interpret it using the trigger prompt.

{
  "message": "Investigate why ticket ENG-421 is failing in checkout and post your findings back to Jira."
}

Example cURL request

curl -X POST "https://agent.kognita.co/triggers/invoke" \
  -H "Content-Type: application/json" \
  -H "X-Kognita-Auth: <trigger-auth-token>" \
  -H "X-Organisation-Id: <organization-uuid>" \
  -H "X-Project-Id: <project-uuid>" \
  -d '{
    "message": "Review the linked pull request and explain whether it changes billing behavior."
  }'

What the caller receives

A valid trigger returns immediately with 202 Accepted. The response includes an invocation ID, but it does not include the agent's final answer. Agent work can take several minutes, so results are delivered through the tools and instructions available to the agent. You can also poll the invocation status endpoint with the returned ID.

{
  "status": "accepted",
  "invocation_id": "4f14b4c8-9b4f-4f44-b275-0a5c4b3c21d7"
}

Poll invocation status

Use the returned invocation ID to periodically query the gateway. The status endpoint uses the sameX-Kognita-Auth,X-Organisation-Id, andX-Project-Id headers as the original POST request. The invocation ID is not a secret by itself.

GET https://agent.kognita.co/triggers/invocations/f84c8753-8eb7-439c-a797-5bd8c23de716
X-Kognita-Auth: <trigger-auth-token>
X-Organisation-Id: <organization-uuid>
X-Project-Id: <project-uuid>

curl "https://agent.kognita.co/triggers/invocations/f84c8753-8eb7-439c-a797-5bd8c23de716" \
  -H "X-Kognita-Auth: <trigger-auth-token>" \
  -H "X-Organisation-Id: <organization-uuid>" \
  -H "X-Project-Id: <project-uuid>"

While the background run is still active, done isfalse and the status is usuallyaccepted. When the run finishes, the response includes the final status, error if any, response text if available, and duration.

{
  "invocation_id": "f84c8753-8eb7-439c-a797-5bd8c23de716",
  "trigger_uuid": "7b08c1f0-1c5c-47df-978a-f80cce2721e9",
  "trigger_name": "Jira review",
  "organization_uuid": "<organization-uuid>",
  "project_uuid": "<project-uuid>",
  "done": true,
  "status": "success",
  "http_status": 202,
  "error_message": null,
  "response_text": "Posted findings to the Jira issue.",
  "duration_ms": 184221,
  "created_at": "2026-05-24T12:30:11",
  "updated_at": "2026-05-24T12:33:15"
}

Invocation history and audit trail

Every trigger card includes an invocation history. It is paginated, starts with the latest call, and shows the status, HTTP code, duration, timestamp, full request, full response, and any error recorded by the gateway.

• Rejected calls are recorded with their rejection status, such as missing headers, bad request, or unauthorized.
• Accepted calls are first recorded as accepted, then updated to success, agent_error, or agent_unavailable when the background run finishes.
• The raw trigger token is never stored in the invocation log; the gateway stores only a fingerprint.
• If the gateway restarts after accepting a run but before updating the row, the invocation can remain in accepted state even if the agent completed its side effect.

Common use cases

Related documentation