Base URL http://localhost:3333/api/ · Authentication · Conventions

Content Output Routes

Base path: /api/content-outputs

Health Check

GET /health

Authentication: None
Description: Check if the content output service is running
Response:

{
  "status": "OK"
}

Get All Content Outputs

GET /

Authentication: Required
Description: Retrieve all content outputs for the authenticated user
Response:

[
  {
    "id": "output-id",
    "title": "Output Title",
    "content": "Content data",
    "workflowId": "workflow-id",
    "toolId": "tool-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Save/Update Content Output

POST /save

Authentication: Required
Description: Create a new content output or update an existing one
Body:

{
  "id": "optional-output-id",
  "title": "Output Title",
  "content": "Content data",
  "workflowId": "workflow-id",
  "toolId": "tool-id"
}

Response:

{
  "success": true,
  "output": {
    "id": "output-id",
    "title": "Output Title",
    "content": "Content data",
    "workflowId": "workflow-id",
    "toolId": "tool-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Get Content Output by ID

GET /:id

Authentication: Required
Parameters:
- id (path): Content output ID
Description: Retrieve a specific content output by ID
Response:

{
  "id": "output-id",
  "title": "Output Title",
  "content": "Content data",
  "workflowId": "workflow-id",
  "toolId": "tool-id",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Update Content Output

PUT /:id

Authentication: Required
Parameters:
- id (path): Content output ID
Body:

{
  "title": "Updated Title",
  "content": "Updated content data"
}

Response:

{
  "success": true,
  "output": {
    "id": "output-id",
    "title": "Updated Title",
    "content": "Updated content data",
    "workflowId": "workflow-id",
    "toolId": "tool-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Rename Content Output

PATCH /:id/rename

Authentication: Required
Parameters:
- id (path): Content output ID
Body:

{
  "title": "New Title"
}

Response:

{
  "success": true,
  "output": {
    "id": "output-id",
    "title": "New Title",
    "content": "Content data",
    "workflowId": "workflow-id",
    "toolId": "tool-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Delete Content Output

DELETE /:id

Authentication: Required
Parameters:
- id (path): Content output ID
Description: Delete a content output by ID
Response:

{
  "success": true,
  "message": "Content output deleted successfully"
}

Get Content Outputs by Workflow

GET /workflow/:workflowId

Authentication: Required
Parameters:
- workflowId (path): Workflow ID
Description: Retrieve all content outputs for a specific workflow
Response:

[
  {
    "id": "output-id",
    "title": "Output Title",
    "content": "Content data",
    "workflowId": "workflow-id",
    "toolId": "tool-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Get Content Outputs by Tool

GET /tool/:toolId

Authentication: Required
Parameters:
- toolId (path): Tool ID
Description: Retrieve all content outputs for a specific tool
Response:

[
  {
    "id": "output-id",
    "title": "Output Title",
    "content": "Content data",
    "workflowId": "workflow-id",
    "toolId": "tool-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Artifacts

The Artifacts system is the in-app workspace for creating and editing files with an AI assistant named Annie. It is not a CRUD resource API — instead, all file operations happen through a single streaming chat endpoint that routes tool calls to filesystem operations against the user's configured workspace root.

Storage

Default workspace root: ~/.agnt/projects/
Configurable via: ~/.agnt/code-settings.json → workspaceRoot field
Enforced path validation: All tool calls resolve paths against the workspace root and reject any path traversal outside it.
Settings API: Workspace root can also be read/updated via the FileSystem Routes (GET /api/filesystem/settings, PUT /api/filesystem/settings).

Chat Endpoint

POST /api/orchestrator/artifact-chat

Authentication: Required
Content-Type: multipart/form-data
Body:
- message (string): User message to Annie
- codeContext (object, optional): Current editor context (active file path, selection, open files). Used by the system prompt to tailor responses.
- files (file[]): Optional file attachments (max 20MB each)
Description: Streaming chat handler that drives the Artifacts workspace. The handler uses the artifact chat configuration (maxToolRounds: 25, responseType: stream) and exposes the four workspace file tools below to the LLM.
Response: Server-sent events stream (tokens, tool-call events, file events)

Workspace Tools (called by the LLM)

These tools are not called directly over HTTP — they are invoked by the LLM during an /artifact-chat turn. They are listed here so integrators understand what Annie can do and what events fire.

`read_file`

Read the contents of a file from the workspace.

Parameters:
- path (string): Relative path within the workspace root
Returns: File content as UTF-8 text, or an error message if the file does not exist

`write_file`

Create or overwrite a file in the workspace. Automatically creates any missing parent directories.

Parameters:
- path (string): Relative path within the workspace root
- content (string): Full file content
Returns: Success confirmation
Side effects: Emits a file_written event to the frontend so the file tree and open editor tabs can refresh

`edit_file`

Surgical search-and-replace edits on an existing file. Preferred over write_file for modifications because it preserves surrounding content and uses fuzzy whitespace matching to tolerate indentation drift.

Parameters:
- path (string): Relative path within the workspace root
- edits (array): List of { search, replace } pairs applied in order
- description (string, optional): Human-readable summary of the change
Returns: Per-edit applied/failed summary
Side effects: Emits file_written on success

`list_files`

List the contents of a workspace directory. Hidden entries (starting with .) are filtered out.

Parameters:
- path (string, optional): Relative directory path, defaults to workspace root
Returns:

[
  { "name": "README.md", "type": "file", "path": "README.md" },
  { "name": "src", "type": "dir", "path": "src" }
]

Configuration Reference

Location	Setting	Purpose
`backend/src/services/orchestrator/chatConfigs.js`	`artifact` entry	Tool schemas, system prompt, `maxToolRounds: 25`, `contextKey: 'codeContext'`
`backend/src/services/orchestrator/system-prompts/artifact-chat.js`	System prompt	Annie persona, preview capabilities, design guidance
`backend/src/services/orchestrator/codeTools.js`	Tool implementations	`read_file`, `write_file`, `edit_file`, `list_files` with path validation
`~/.agnt/code-settings.json`	`workspaceRoot`	Per-user workspace root override

Files outside chat: Use FileSystem Routes (/api/filesystem/*) to read, write, rename, and delete workspace files directly over HTTP (e.g., for the editor panel or external tooling).
Persisted artifacts: Generated content that the user saves is stored via Content Output Routes (/api/content-outputs) and can be organized with Group Routes.

Image Routes

Base path: /api/images

Serves images generated by the image-generation tools.

Get Image