Build on Aktor

Step by step: your first solution

From a template to an assistant and workflows running inside your own app, with the code.

This is the whole path, in the order the dashboard takes you.

1. Start from a template. Solutions → Templates → Helpdesk → Use this template. The builder opens a copy as a draft. (Or New solution and describe your app to Design with AI.)

2. Make it yours. In the builder:

  • Basics: a title.
  • Assistant → Allowed sites: the sites that will embed it, e.g. https://app.acme.com.
  • Assistant → Monthly cost cap per customer: e.g. 2.

Review & deploy says ✓ Valid when it's ready.

3. Deploy. Give the inputs it asks for. You land on the solution's Integrate tab.

4. Try it without code.

  • Data: create a Ticket and watch the triage workflow classify it.
  • Assistant: chat as a customer.
  • Evals: Run all.

5. Create an app key. Integrate → App keys → Create key, then store it as server secrets:

AKTOR_URL=https://your-aktor.example.com
AKTOR_INSTALL_ID=sol-…
AKTOR_APP_KEY=aks_…        # shown once; never put it in front-end code

Check it from your server; the checklist's "has connected" step turns green:

curl -s $AKTOR_URL/api/v1/apps/$AKTOR_INSTALL_ID -H "Authorization: Bearer $AKTOR_APP_KEY"

6. One client, on your server. The TypeScript SDK (@aktor/sdk) is coming soon; until then, the Integrate tab's Any language (HTTP) option gives the same calls as plain HTTP. With the SDK:

// lib/aktor.ts
import { AktorServer } from "@aktor/sdk";
export const aktor = new AktorServer({ installId: process.env.AKTOR_INSTALL_ID!, appKey: process.env.AKTOR_APP_KEY!, baseUrl: process.env.AKTOR_URL });

7. Put the assistant on your site. A token endpoint the widget POSTs to, after your own sign-in:

// app/api/aktor-token/route.ts (Next.js)
import { aktor } from "@/lib/aktor";
import { getCurrentUser } from "@/lib/auth";

export async function POST() {
  const user = await getCurrentUser();
  if (!user) return new Response("Sign in first", { status: 401 });
  const { token } = await aktor.issueToken(user.id, { name: user.name });
  return Response.json({ token });
}
<script src="https://your-aktor.example.com/embed.js" data-install="sol-…" data-token-url="/api/aktor-token" async></script>

8. Run a workflow from your code and get its result:

const run = await aktor.run("intake", { subject: "Charged twice", message: "Please refund one." },
  { idempotencyKey: "contact-8841" });   // a retried submit returns the same run
console.log(run.status, run.summary);

9. Read and write its records:

const { items } = await aktor.records.list("Ticket", { where: { status: "awaiting_review" } });
await aktor.records.update("Ticket", items[0].id, { status: "answered" }, { ifMatch: items[0].version });

10. Go live when the Integrate tab's checklist is all green:

  • the key is created and has connected;
  • allowed sites are set;
  • a cap per customer is set;
  • evals pass.

After that:

  • Change it: in the builder, raise the version and deploy. Only what changed is applied.
  • Bill for it: the Usage tab.
  • Rotate keys: create a new one, then revoke the old.