Add knowledge to Last9 AI

Give Last9 AI your app context: runbooks, service notes, and investigation procedures. Knowledge topics can also bind tools from remote MCP servers so incident workflows call the right tools with the approval policy you choose.

Prerequisites

• Last9 AI enabled for your organization. See Enable Last9 AI.
• An Admin user (writes need an administrator).
• An API refresh token with write scope to create or update, and delete scope to remove topics or documents. See Getting started with API.
• Your organization slug (from the dashboard URL: app.last9.io/v2/organizations/<org_slug>/...).
• Optional: a remote MCP server already registered if you will bind tools. See Remote MCP servers.

What a knowledge topic contains

use: ["incident_triage"] makes the topic eligible on investigation / incident turns. Omit use or set [] when creating through the API to keep the topic out of investigations. The topic stays readable through the management APIs and can still appear in regular AI Assistant chats.

Create a topic and upload runbooks

Worked example: topic payments-incident-playbook bound to a remote MCP server named payments. Register that server first if you need tool bindings.

1. Mint an access token

   curl -sS -X POST 'https://app.last9.io/api/v4/oauth/access_token' \
     -H 'Content-Type: application/json' \
     -d '{"refresh_token":"<refresh_token>"}'
   
   export LAST9_TOKEN='<access_token>'
   export LAST9_ORG='<org_slug>'
   export LAST9_AI="https://app.last9.io/api/v4/organizations/${LAST9_ORG}/ai"

2. Create an incident knowledge topic

   curl -sS -X POST "${LAST9_AI}/knowledge/topics" \
     -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}" \
     -H 'Content-Type: application/json' \
     -d '{
       "id": "payments-incident-playbook",
       "name": "Payments incident playbook",
       "description": "How to triage payments and ledger incidents",
       "overview": "For SEV1/2 payments incidents: call get_incident on the payments MCP, then Last9 traces and logs for the same service and window, then add_comment. Prefer payments-incident-playbook__* tools over raw mcp__payments__* names.",
       "use": ["incident_triage"],
       "mcp": [
         {"server": "payments", "tools": ["get_incident", "add_comment"], "approval": "auto"},
         {"server": "payments", "tools": ["close_incident"], "approval": "approve"}
       ]
     }'

   Field	Meaning
   use: ["incident_triage"]	Topic is eligible on investigation / incident turns.
   mcp[].server	Must already exist in GET /mcp-servers.
   mcp[].tools	Allowlist of tool names, or ["*"] for every tool on that server.
   mcp[].approval	auto runs without a UI click; approve (default) requires human confirmation.
   overview	Short procedure. Put the when and order of tools here.

   use is a closed list. Unknown values return 400. You can create a topic without mcp and add bindings later with PATCH. Expected create response: 201 with activation.status: "pending".

   Topic and document id values must be lowercase kebab-case ([a-z0-9]+(?:-[a-z0-9]+)*). Underscores are rejected.

3. Upload app knowledge documents

   JSON body:

   curl -sS -X POST "${LAST9_AI}/knowledge/topics/payments-incident-playbook/documents" \
     -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}" \
     -H 'Content-Type: application/json' \
     -d '{
       "id": "sev1-runbook",
       "title": "SEV1 payments runbook",
       "content": "## SEV1\n1. Confirm affected merchant and region.\n2. Call get_incident.\n3. Correlate with Last9 error rate and traces.\n4. add_comment with findings.\n5. close_incident only after human approval."
     }'

   Or upload a file (text/plain, text/markdown, or .docx). PDF returns 415. Extracted text is stored; uploads do not install executable tools.

   curl -sS -X POST "${LAST9_AI}/knowledge/topics/payments-incident-playbook/documents" \
     -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}" \
     -F 'id=sev1-runbook' \
     -F 'title=SEV1 payments runbook' \
     -F 'file=@./sev1-runbook.md;type=text/markdown'

4. Activate with a chat turn

   After create or PATCH, activation.status is pending. Open AI Assistant (or start an investigation) and send a turn. Then check:

   curl -sS "${LAST9_AI}/config/status" \
     -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}"

   Expect active.

5. Verify in an investigation

   Ask about a payments incident and instruct the assistant to follow the playbook. Bound tools appear as {topic_id}__{tool} — for example payments-incident-playbook__get_incident — with the approval you configured.

   Raw names mcp__payments__get_incident remain available for API-managed servers but still default to approve, even when the topic binding says auto. Prefer the topic-prefixed tools in the overview so auto-approved paths are used.

List and read

curl -sS "${LAST9_AI}/knowledge" \
  -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}"

curl -sS "${LAST9_AI}/knowledge/topics" \
  -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}"

curl -sS -D - "${LAST9_AI}/knowledge/topics/payments-incident-playbook" \
  -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}" -o /tmp/topic.json

Keep the quoted ETag from the topic GET for PATCH or DELETE.

Update or remove

curl -sS -X PATCH "${LAST9_AI}/knowledge/topics/payments-incident-playbook" \
  -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "<etag_from_get>"' \
  -d '{"overview":"Updated procedure…"}'

Clear MCP bindings or opt out of triage:

curl -sS -X PATCH "${LAST9_AI}/knowledge/topics/payments-incident-playbook" \
  -H "X-LAST9-API-TOKEN: Bearer ${LAST9_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "<etag>"' \
  -d '{"mcp": [], "use": []}'

Missing If-Match returns 428; a stale value returns 412. Delete topics or documents with DELETE and the same precondition header (needs delete scope).

How tools and approval behave

Investigation turns only load knowledge topics whose use includes incident_triage. Topics created through the API default to use: [] and stay out of investigations until you opt them in.

Checklist

1. Admin has AI enabled and an API refresh token with write and delete scopes.
2. Remote MCP (if needed) is registered and healthy. See Remote MCP servers.
3. Topic exists with use: ["incident_triage"], a concrete overview, and mcp bindings for the tools the runbook needs.
4. At least one document holds the detailed runbook (markdown preferred).
5. After one AI Assistant turn, GET /config/status is active.
6. A test investigation calls a topic-prefixed tool; auto tools run without a click, approve tools wait for confirmation.

Related

• Remote MCP servers — register and test remote MCP endpoints
• AI Assistant — run a verification chat after activation
• Investigate an incident with AI — investigation method
• Getting started with API — refresh and access tokens

Troubleshooting

Please get in touch with us on Discord or Email if you have any questions.