Agents API lets you consume conversations from your Aki Agent Web projects through an external application. This allows you to automate tasks with code while using your Aki Agent in other applications. The response is delivered as an SSE event stream, so you can display it as it is generated instead of waiting for the entire process to finish.

IMPORTANT: This feature is experimental and may change at any time.

Before you start

1. Go to My account → Agents API.
2. Create an API key and save the complete secret. Aki Agent does not store the secret in plaintext, so it will only display it once.
3. Use the API key in the Authorization header of every request.
4. Use a project ID that belongs to you, or let the API create a project for the first test.

Endpoint

The public endpoint is:

POST https://aki.ar/api/agents/v1/chat
Authorization: Bearer akia_live_...
Content-Type: application/json
Accept: text/event-stream

The test form at the end of this page sends the key directly from your browser to the endpoint and does not save it. For a real integration, keep the key on your application server and never include it in frontend code or a repository.

Send a message to an existing project

The project_id must belong to the same user who created the API key. The message field supports a maximum of 5,000 characters.

curl -N "https://aki.ar/api/agents/v1/chat" \
  -H "Authorization: Bearer akia_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": 123,
    "message": "Analyze the project and suggest three concrete improvements.",
    "model": "AUTO"
  }'

The cURL -N option prevents the stream output from accumulating before it is displayed.

Create a project automatically

If you do not have a project yet, omit project_id and send create_project: true. You can also provide project_name and design_preferences for the initial values.

curl -N "https://aki.ar/api/agents/v1/chat" \
  -H "Authorization: Bearer akia_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "create_project": true,
    "project_name": "Project created by API",
    "design_preferences": {
      "style": "minimal",
      "primary_color": "#2563EB"
    },
    "message": "Create the initial structure for a coffee shop landing page.",
    "model": "openai/gpt-5.6-luna"
  }'

Values for `model`

model is optional and defaults to AUTO. Some values you can send are:

• AUTO: the recommended router for choosing a model based on the task.
• openai/gpt-5.6-luna: general tasks, questions, and writing with good speed.
• openai/gpt-5.3-codex: programming, data analysis, and code generation.
• anthropic/claude-sonnet-5: creative writing, deep analysis, and long tasks.
• x-ai/grok-4.6: advanced reasoning and programming.

Availability, cost, and limits depend on your account. Send the model value, not an environment variable name. For example: "model": "AUTO" or "model": "openai/gpt-5.6-luna".

Long messages: contexts and skills with `@`

The message limit is 5,000 characters per request. Do not try to bypass it by concatenating very long instructions. If you need to reuse instructions, criteria, or extended information, create a context or a prepared skill in the chat and call it with @ when needed, for example @brief-brand, @mermaid, or @plan. This keeps the message focused on the immediate task.

You can write one or more mentions directly inside message. The API resolves them against the enabled contexts and credentials belonging to the user who owns the API key, for example:

{
  "message": "@brief-brand Apply this context to the screen and also use @imagen-social when relevant.",
  "model": "AUTO"
}

Resolution is scoped to the user, not global or tied only to project_id. If an integration already knows the slugs, it can also send contexts through selected_skills:

{
  "message": "Apply the brand context to this screen.",
  "model": "AUTO",
  "selected_skills": [
    {
      "source": "contexto",
      "skillId": "brief-brand",
      "name": "@brief-brand",
      "repoUrl": "",
      "skillsUrl": ""
    }
  ]
}

You can also invoke built-in skills such as @mermaid by mentioning them in message; selected_skills, selected_collections, and attachment_ids are arrays of up to 100 items.

JavaScript example

The endpoint returns text/event-stream. This example reads the received chunks; your client can process each SSE event according to its needs.

const response = await fetch(`${BASE_URL}/api/agents/v1/chat`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENTS_API_KEY}`,
    Accept: "text/event-stream",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    project_id: 123,
    message: "Review the code and explain the main problems.",
    model: "openai/gpt-5.3-codex",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const reader = response.body?.getReader();
if (!reader) throw new Error("The response does not contain a stream");

const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value, { stream: true }));
}

Available fields

• message is required and supports between 1 and 5,000 characters.
• project_id is required unless you send create_project: true.
• project_name and design_preferences are used when creating a new project.
• model is optional; AUTO is used by default.
• selected_skills, selected_collections, and attachment_ids are arrays of up to 100 items.
• ui_theme can be light or dark.

Common errors

• 400: invalid JSON, missing message, invalid project_id, or missing create_project.
• 401: missing, invalid, or revoked API key.
• 403: the account is suspended.
• 404: the project does not exist or does not belong to the key's user.
• 413: the message exceeds 5,000 characters.
• 429: the request limit was exceeded.
• 502: the chat service could not be reached.

Revoke an API key

You can revoke a key from My account → Agents API. Integrations using it will stop authenticating immediately.