Content & Artifacts

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

Related Endpoints

• 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

GET /:id

• Authentication: Required
• Description: Serves a stored generated image by id with the correct content type and Cache-Control: private, max-age=31536000, immutable. 404 if not found.
• Response: Image bytes

---

Local File Routes

Base path: /api/local-file

Streams local files over HTTP with Range support. The chat renderer rewrites file:/// URLs to this endpoint so <video> seeking, large images, and PDF embeds work.

Serve Local File

GET /?path=<path> or GET /<path>

• Authentication: Required. requireAuthMedia accepts a bearer header, ?token=, or the agnt_media_token cookie — the cookie is the only carrier that survives relative-URL resolution inside injected HTML, so <img src="/api/local-file/..."> works from rendered content.
• Description: Two equivalent forms — legacy query-string (/api/local-file?path=...) and path-based (/api/local-file/<path>). Supports HTTP Range requests (206 Partial Content) for media seeking.
• Response: File bytes (200 or 206); 416 on an invalid range; 500 on failure

---