Agents v1 API

Overview

The Agents v1 API exposes a remote-model-compatible surface for discovering agent-backed models, listing deferred tools, activating tools for a session, and retrieving completed responses. It mirrors the shape expected by remote-model clients so that Allternit agents can be consumed through standard SDKs while still preserving Allternit-specific profile metadata. An “agent-backed model” here is an agent profile presented in a model-compatible shape: its id is the agent ID. modelConfig is the real model configuration the agent runs with, taken from the agent’s profile config and falling back to the agent’s provider and model columns.

Existing runtime/provider APIs expose implementation controls intentionally. The Agency API is the abstraction that hides those controls behind capabilities and one durable agent identity. See Agents API vs Agency API.

Base URL

https://api.allternit.com/api

For local development:

http://127.0.0.1:8013/api

Authentication

All routes require a valid bearer token in the Authorization header. See Authentication for details.

Agent profile object

A remote model entry returned by this API wraps an Allternit agent profile.

Field	Type	Description
`agentId`	string	Unique agent identifier.
`version`	string	Profile version.
`avatarUrl`	string \| null	Agent avatar URL.
`instructions`	string	Composed system instructions.
`modelConfig`	object	`provider`, `model`, `temperature`, `maxContextTokens`, `maxOutputTokens`, `maxSteps`.
`capabilities`	object	Capability flags such as `execute_code`, `file_search`, `mcp_tools`, `artifacts`, `computer_use`, etc.
`toolPolicy`	object	`builtInToolIds`, `mcpServerIds`, `allowedMcpToolIds`, `deferredToolIds`.
`files`	any \| null	Attached file references.
`artifactPolicy`	any \| null	Artifact publishing policy.

Endpoints

Method	Path	Description
`GET`	`/agents-v1`	Service status.
`GET`	`/agents/v1/models`	List agent-backed models for the authenticated user.
`GET`	`/agents/v1/models/:model`	Retrieve a single agent-backed model.
`GET`	`/agents/v1/responses/models`	Alias for listing agent-backed models.
`GET`	`/agents/v1/tools`	List tools available to a model.
`POST`	`/agents/v1/tools/search`	Search tools available to a model.
`POST`	`/agents/v1/tools/activate`	Activate tools for a session.
`GET`	`/agents/v1/responses/:id`	Retrieve a completed response by ID.

List agent-backed models

curl https://api.allternit.com/api/agents/v1/models \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "agent_01J8X...",
      "object": "model",
      "created": 1723500000,
      "owned_by": "allternit",
      "profile": {
        "agentId": "agent_01J8X...",
        "version": "1",
        "instructions": "You are a helpful coding assistant.",
        "modelConfig": {
          "provider": "ollama",
          "model": "qwen2.5:0.5b",
          "temperature": 0.2,
          "maxContextTokens": null,
          "maxOutputTokens": null,
          "maxSteps": 10
        },
        "capabilities": {
          "execute_code": true,
          "mcp_tools": true
        },
        "toolPolicy": {
          "builtInToolIds": ["markdown-to-doc"],
          "mcpServerIds": [],
          "allowedMcpToolIds": [],
          "deferredToolIds": []
        }
      }
    }
  ]
}

Retrieve a model

curl https://api.allternit.com/api/agents/v1/models/agent_01J8X... \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

Returns a single model object identical to the items returned by the list endpoint.

List tools

curl "https://api.allternit.com/api/agents/v1/tools?model=agent_01J8X..." \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "markdown-to-doc",
      "label": "Markdown to document",
      "serverId": "allternit-api",
      "description": "Convert markdown content to a formatted document.",
      "parameters": {}
    }
  ],
  "model": "agent_01J8X..."
}

Search tools

curl -X POST https://api.allternit.com/api/agents/v1/tools/search \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent_01J8X...",
    "query": "markdown"
  }'

Filters the model’s available tools by a case-insensitive substring match on id, label, or description. Returns the same shape as List tools: {"object": "list", "data": [...], "model": "agent_01J8X..."}. An unknown agent returns 404.

Activate tools

Activate one or more tools for a session so they appear in the runtime tool snapshot. tool_ids must contain at least one ID (otherwise 400). If the session does not exist yet, a remote session is created for it.

curl -X POST https://api.allternit.com/api/agents/v1/tools/activate \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent_01J8X...",
    "session_id": "ses_abc123",
    "tool_ids": ["markdown-to-doc"]
  }'

Response

{
  "success": true,
  "sessionId": "ses_abc123",
  "model": "agent_01J8X...",
  "activatedToolIds": ["markdown-to-doc"]
}

Retrieve a response

Fetch a previously generated assistant response by its response ID.

curl https://api.allternit.com/api/agents/v1/responses/resp_abc123 \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

Response

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1723500000,
  "status": "completed",
  "model": "agent_01J8X...",
  "output_text": "The answer is 42.",
  "output": [
    {
      "id": "msg_resp_abc123",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The answer is 42.",
          "annotations": [],
          "logprobs": []
        }
      ]
    }
  ],
  "allternit": {
    "conversation_id": "conv_abc123",
    "agent_profile": null,
    "artifacts": []
  }
}

Error codes

HTTP status	Code	Meaning
400	`allternit.invalid_request`	Missing required fields such as `tool_ids`.
401	`allternit.authentication_failed`	Missing or invalid bearer token.
404	`allternit.not_found`	Agent, model, or response not found.
500	`allternit.internal_error`	Database or runtime internal error.

Agents API — create and manage agents
Agent Sessions — chat sessions and message history
MCP Servers — attach model context protocol servers

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Agent profile object

Endpoints

List agent-backed models

Response

Retrieve a model

List tools

Response

Search tools

Activate tools

Response

Retrieve a response

Response

Error codes

​Overview

​Base URL

​Authentication

​Agent profile object

​Endpoints

​List agent-backed models

​Response

​Retrieve a model

​List tools

​Response

​Search tools

​Activate tools

​Response

​Retrieve a response

​Response

​Error codes

​Related pages

Overview

Base URL

Authentication

Agent profile object

Endpoints

List agent-backed models

Response

Retrieve a model

List tools

Response

Search tools

Activate tools

Response

Retrieve a response

Response

Error codes

Related pages