⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
Agent endpoint
An external agent gets its tasks in one of two ways:
- A runner on your machine asks the instance for the tasks. See Coding agent setup.
- The instance sends the tasks to an endpoint that you run: an AWS Lambda function URL, an Azure Function, a Cloudflare Worker, or any other HTTPS server.
This page describes the endpoint.
The endpoint gets the same tasks as a runner: delegations, mentions, field and status triggers, schedules, manual runs, and chat messages. Each task has the same prompt and system prompt. The endpoint sends the result through the same routes as a runner.
Set it up
- Create an external agent. Copy its API key.
- In the agent's Connection section, select Endpoint. Enter the URL and save.
- Copy the signing secret below the URL.
- Click Send test. The section shows the status code of the answer and the start of its body.
The URL must use HTTPS and resolve to a public address. To use a private host, add it to
SSRF_ALLOWED_HOSTS on the instance. That host must also use HTTPS.
When NODE_ENV on the instance is not production or test, the instance also accepts
http:// and private addresses, for example http://localhost:4000. Use this to test a
local server before you deploy the function.
While the agent has a URL, the runner claim routes (POST /agent-runs/claim,
POST /agent-chats/claim) answer 409. To connect a runner again, clear the URL.
Requests
The instance sends each task as one POST request with a JSON body and these headers:
| Header | Value |
|---|---|
Content-Type |
application/json |
X-Itsaplan-Event |
agent.run, agent.chat or ping |
X-Itsaplan-Signature |
t=<unix seconds>,v1=<hex HMAC-SHA256> |
The body of an agent.run request:
{
"event": "agent.run",
"agent": { "id": 12, "username": "cloud-bot" },
"apiUrl": "https://api.example.com",
"run": {
"id": 345,
"trigger": "status",
"prompt": "The task, framed with what started it",
"systemPrompt": "The project, the people, and the agent's instructions",
"attempts": 1,
"issueId": 678,
"issueIdentifier": "MKT-42"
}
}
apiUrl is the API_URL of the instance, or null if API_URL is not set. An
agent.chat request has message instead of run:
{
"id": 901,
"threadId": "chat:12:...",
"prompt": "The person's message, after the earlier turns",
"systemPrompt": "The projects, the person, and the agent's instructions",
"attempts": 1,
"sessionId": null
}
A ping request has only event, agent and apiUrl. Send test sends a ping.
Verify the signature
The signature is an HMAC-SHA256 of <t>.<raw body>. The key is the signing secret.
Calculate it on the raw body, before you parse the JSON:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const given = Buffer.from(v1 ?? '');
const wanted = Buffer.from(expected);
return given.length === wanted.length && timingSafeEqual(given, wanted);
}
Project webhooks use the same signature, with the secret of the webhook.
Answer
The status code of the answer tells the instance what to do with the task:
- 2xx. The endpoint accepted the task. The instance leases the task for
AGENT_RUN_LEASE_SECONDS(chat:AGENT_CHAT_LEASE_SECONDS), 300 seconds by default. A heartbeat extends the lease. The result closes the task. If the lease ends before the result, the instance sends the task again. It sends a task at mostAGENT_RUN_MAX_ATTEMPTStimes (chat:AGENT_CHAT_MAX_ATTEMPTS), 3 by default. - Other status code, or a connection error. The instance sends a run again after a delay. The first delay is up to 30 seconds. Each next delay is longer, up to 30 minutes. After the last attempt, the run fails. A chat message fails immediately, because a person waits for the answer.
- No answer in
AGENT_INVOCATION_TIMEOUT_MS(15 seconds by default). The instance treats the task as accepted and keeps it leased. Thus an endpoint that does the work before it answers does not get the same task again while the lease lasts.
The instance does not use the body of the answer. Only Send test shows it. The result of a task comes only through the routes below.
Send the result
Call the API at apiUrl. Put the agent's API key in the x-api-key header:
| Route | Body |
|---|---|
POST /agent-runs/:runId/heartbeat |
none |
POST /agent-runs/:runId/result |
{ "status": "success" | "failed", "output", "error" } |
POST /agent-chats/:messageId/events |
{ "events": [AG-UI events], "sessionId" } |
POST /agent-chats/:messageId/heartbeat |
none |
POST /agent-chats/:messageId/result |
{ "status": "success" | "failed", "error" } |
A chat answer is a sequence of AG-UI events. Send a TEXT_MESSAGE_CONTENT event with a
delta for each part of the text. Send the tool call events for each tool that the agent
uses. When the person stops the answer, the events, heartbeat and result routes of that
answer return { "canceled": true }. Then stop the work on that answer.
The agent reads and changes issues with the same key, through the REST API or the MCP
server at <apiUrl>/mcp.
With the runner
With listen, @itsaplan/runner is the endpoint. It receives the tasks on a port and
runs them with a coding agent CLI, the same as when it polls. See
Receiving tasks on a port.
Example: AWS Lambda
A Node.js handler for a Lambda function URL. Set ITSAPLAN_API_KEY and
ITSAPLAN_SIGNING_SECRET in the environment of the function:
import { createHmac, timingSafeEqual } from 'node:crypto';
const api = (base, path, body = {}) =>
fetch(`${base}${path}`, {
method: 'POST',
headers: { 'x-api-key': process.env.ITSAPLAN_API_KEY, 'content-type': 'application/json' },
body: JSON.stringify(body),
});
export const handler = async (event) => {
const raw = event.isBase64Encoded ? Buffer.from(event.body, 'base64').toString() : event.body;
const signature = event.headers['x-itsaplan-signature'] ?? '';
if (!verify(process.env.ITSAPLAN_SIGNING_SECRET, signature, raw)) {
return { statusCode: 401, body: 'bad signature' };
}
const payload = JSON.parse(raw);
if (payload.event === 'agent.run') {
const output = await doTheWork(payload.run); // your agent: a model call, a pull request
await api(payload.apiUrl, `/agent-runs/${payload.run.id}/result`, {
status: 'success',
output,
});
}
return { statusCode: 200, body: 'ok' };
};
verify is the function from Verify the signature. A function URL
keeps the request open until the handler returns. Thus this handler answers after the
work. The instance stops the wait after 15 seconds and keeps the task leased. For work
longer than the lease, do one of these:
- Send heartbeats.
- Invoke a second function asynchronously with the task, and answer immediately.