Public automation API

Use the public automation API when an external app needs to start an approved AKOS automation without exposing the internal JSON-RPC surface. Create scoped keys in Connections › External apps. For workspace-internal webhook triggers (sidecar paths, not hosted automation URLs), see Triggers.

Choose a path

Never put AGENTSKIT_API_KEY in browser code, public .env files, client components, or generated frontend snippets.

Create an API key

1. Open Connections.
2. Select External apps.
3. Create a scoped key with the automations it may run.
4. Copy the raw key once and store it in your server environment as AGENTSKIT_API_KEY.

Keys are stored by hash. AKOS shows the raw secret only when the key is created.

Server-side run

export async function POST(req: Request) {
  const input = await req.json()
  const res = await fetch(`${process.env.AGENTSKIT_API_URL}/v1/automations/run`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      authorization: `Bearer ${process.env.AGENTSKIT_API_KEY}`,
      'idempotency-key': input.id ?? crypto.randomUUID(),
    },
    body: JSON.stringify({
      automationId: 'lead-intake',
      input,
      mode: 'real',
    }),
  })
 
  if (!res.ok) return Response.json({ error: 'automation_failed' }, { status: 502 })
  return Response.json(await res.json())
}

Use this from Lovable, v0, Next, Vercel, or any app builder by calling your own server endpoint. The app builder should never receive the AKOS key.

Hosted webhook

Create or edit a webhook trigger in Automations > Triggers. The form shows the hosted endpoint:

POST https://your-akos-host/v1/automations/webhooks/lead-intake
Authorization: Bearer ak_live_...
Content-Type: application/json
Idempotency-Key: lead-form-123

Example:

curl -X POST 'https://your-akos-host/v1/automations/webhooks/lead-intake' \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <AGENTSKIT_API_KEY>' \
  -H 'idempotency-key: lead-form-123' \
  -d '{"email":"ana@acme.com","message":"hello"}'

The request body becomes the automation input.

Read run status

curl 'https://your-akos-host/v1/automation-runs/pipe_123' \
  -H 'authorization: Bearer <AGENTSKIT_API_KEY>'

Status reads are scoped to runs created by the calling key.

Security notes

• Keys are org-scoped and may be limited to specific automation ids.
• Revoked keys stop before reaching the runner.
• /rpc remains internal-only; external apps only use /v1/automations/*.
• Use Idempotency-Key for form submissions and retries.
• Hosted webhook HMAC secrets are not part of this first version. Use API key auth until a dedicated webhook signing secret is available.

Related screens