Skills, MCP and API

Send your first agent API request

Post one message to the agent from a terminal and get its finished answer back as JSON.

Before you start

You need a personal API token and the address you open Chetty on. Create the token under Account → API tokens if you do not have one yet; see Create and manage a personal API token.

The examples use https://elowen.example.com. Replace it with your own address. Every request goes to the same host, under /api.

Put the address and the token in two shell variables:

export ELOWEN_URL=https://elowen.example.com
export ELOWEN_TOKEN=elw_…   # the token you copied

Check that the token works. The answer names your account:

curl -sS "$ELOWEN_URL/api/auth/me" -H "Authorization: Bearer $ELOWEN_TOKEN"

A missing, unknown, deleted or expired token answers 401 {"error":"unauthorized"}. The same happens after you create a new value for a token: the old value is dead from that moment.

Send a request

Send the message to POST /api/v1/agent/runs. The call runs one ordinary agent turn and answers when the turn is finished.

curl -sS "$ELOWEN_URL/api/v1/agent/runs" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize the failed builds from yesterday"}'

Only message is required. Add conversationId to continue a conversation, model to pick a model (Choose a model through the API) and "stream": true to follow the turn (Stream an agent reply). The API reference lists every field with its type and meaning, read from the request's own schema.

Read the answer

{ "conversationId": "brain-12-…", "reply": "Two builds failed…", "usage": { "tokens": 1840, "costUsd": 0.012 } }

conversationId names the conversation the run used. Send it back to continue that conversation.
reply is the finished answer.
usage.tokens counts the tokens the turn spent.

usage.costUsd is null when nothing priced the run: the provider reported no charge and Chetty has no price for the model, neither a list price from its catalog nor a price set for that model. A price Chetty has is an estimate, and a charge the provider reports itself wins over it, a reported $0 included.

When the call waits too long

The call waits up to two minutes. A longer turn answers 202 with the conversation named and no reply:

{ "conversationId": "…", "reply": null, "usage": null }

The turn keeps running and its answer lands in that conversation. For long work, stream the turn instead of waiting: Stream an agent reply.

Check that it worked

Open the conversation in the web app. Your run is in the conversation history like any other, with the answer the API returned. Its tokens and cost appear against the token that made it.

See Agent API for what else the API can do, and Cap what an API token can run to stop a script from overspending.