# Ajentify API Documentation

Welcome to the Ajentify API documentation. Select an endpoint below to view its documentation.

## Quick Start Guides

| Guide | Description |
|-------|-------------|
| [Web Chat Quick-Start](/docs/web-chat-quickstart) | Embed an Ajentify agent in your web app with `@ajentify/chat` |

## API Reference

### Authentication

| Guide | Description |
|-------|-------------|
| [Authentication Guide](/docs/api/authentication) | API keys, coding agent setup, and security best practices |

Don't have an API key? [Generate one here](https://ajentify.com/api-keys).

## Agent

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/agents](/docs/GET/agents) | Private | List all agents for the authenticated user |
| `POST` | [/agent](/docs/POST/agent) | Private | Create a new AI agent with a system prompt, tools, and configuration |
| `GET` | [/agent/{agent_id}](/docs/GET/agent/{agent_id}) | Public | Retrieve an agent by ID |
| `POST` | [/agent/{agent_id}](/docs/POST/agent/{agent_id}) | Private | Update an existing agent's configuration. Pass `stage_id` and `logical_name` together to attach this agent to a stage so it appears in /deploy manifests and is reachable via runtime addressing on POST /context; pass both as null to detach. If the agent ends up with a stage, every user-defined tool it references is reconciled into the same stage — unattached tools are auto-claimed; tools already in another stage 409. |
| `DELETE` | [/agent/{agent_id}](/docs/DELETE/agent/{agent_id}) | Private | Delete an agent |

## Context

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/context](/docs/POST/context) | Public | Create a new conversation context for an agent. The agent can be addressed in two ways: by its server-assigned `agent_id` (UUID), or by the `(stage, agent)` pair where `stage` is a stable stage name (e.g. 'frontend-staging') and `agent` is the logical name declared in the stage's deploy manifest (e.g. 'cara'). Both forms are accepted; `agent_id` wins if both are provided. |
| `GET` | [/context/{context_id}](/docs/GET/context/{context_id}) | Public | Retrieve an existing context by ID |
| `DELETE` | [/context/{context_id}](/docs/DELETE/context/{context_id}) | Private | Delete an existing context |
| `GET` | [/context-history](/docs/GET/context-history) | Private | Retrieve conversation history. By default returns contexts for the authenticated user. Pass ?client_id=X to fetch contexts for a specific org-owned client; the authenticated caller's org must own that client_id. |
| `POST` | [/context/add-messages](/docs/POST/context/add-messages) | Public | Append messages to an existing context |
| `POST` | [/context/set-messages](/docs/POST/context/set-messages) | Public | Replace all messages in a context |

## Chat

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/chat](/docs/POST/chat) | Public | Send a message to an agent and get a response |
| `POST` | [/chat/add-ai-message](/docs/POST/chat/add-ai-message) | Public | Add an AI message or trigger an AI response with a system prompt |
| `POST` | [/chat/invoke](/docs/POST/chat/invoke) | Public | Invoke the agent without adding a human message |
| `POST` | [/chat/client-side-tool-responses](/docs/POST/chat/client-side-tool-responses) | Public | Submit responses for client-side tool calls and continue the conversation |

## Tool

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/tool](/docs/POST/tool) | Private | Create a new tool with code that agents can execute |
| `GET` | [/tool/{tool_id}](/docs/GET/tool/{tool_id}) | Private | Retrieve a tool by ID |
| `POST` | [/tool/{tool_id}](/docs/POST/tool/{tool_id}) | Private | Update an existing tool. Pass `stage_id` and `logical_name` together to attach this tool to a stage so it appears in /deploy manifests; pass both as null to detach. The tool's Parameter Definition follows the tool's stage binding automatically — attaching to a stage claims the PD into the same stage with logical name `_tool_<logical>_schema`; detaching releases it. |
| `DELETE` | [/tool/{tool_id}](/docs/DELETE/tool/{tool_id}) | Private | Delete a tool |
| `GET` | [/tools](/docs/GET/tools) | Private | List all tools for the user |
| `GET` | [/default-tools](/docs/GET/default-tools) | Private | List all built-in default tools |
| `POST` | [/test-tool](/docs/POST/test-tool) | Private | Test tool code execution without creating the tool |

## Structured Response Endpoint

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/sre](/docs/POST/sre) | Private | Create a structured response endpoint for generating typed JSON output from prompts |
| `GET` | [/sre/{sre_id}](/docs/GET/sre/{sre_id}) | Private | Retrieve an SRE by ID |
| `POST` | [/sre/{sre_id}](/docs/POST/sre/{sre_id}) | Private | Update an existing SRE. Pass `stage_id` and `logical_name` together to attach this SRE to a stage so it appears in /deploy manifests; pass both as null to detach. The SRE's Parameter Definition follows the SRE's stage binding automatically — attaching to a stage claims the PD into the same stage with logical name `_sre_<logical>_schema`; detaching releases it. |
| `DELETE` | [/sre/{sre_id}](/docs/DELETE/sre/{sre_id}) | Private | Delete an SRE |
| `GET` | [/sres](/docs/GET/sres) | Private | List all SREs for the user |
| `POST` | [/run-sre](/docs/POST/run-sre) | Private | Run a one-off structured extraction without creating an SRE or parameter definition |
| `POST` | [/run-sre/{sre_id}](/docs/POST/run-sre/{sre_id}) | Public | Execute an SRE with variable values to generate a structured response |

## Parameter Definition

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/parameter-definition](/docs/POST/parameter-definition) | Private | Create a parameter definition that defines structured input/output schemas |
| `GET` | [/parameter-definition/{pd_id}](/docs/GET/parameter-definition/{pd_id}) | Private | Retrieve a parameter definition by ID |
| `POST` | [/parameter-definition/{pd_id}](/docs/POST/parameter-definition/{pd_id}) | Private | Update an existing parameter definition |
| `DELETE` | [/parameter-definition/{pd_id}](/docs/DELETE/parameter-definition/{pd_id}) | Private | Delete a parameter definition |
| `GET` | [/parameter-definitions](/docs/GET/parameter-definitions) | Private | List all parameter definitions for the user |

## Stage

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/stage](/docs/POST/stage) | Private | Create a new stage. Stages logically group deployed resources (Agents, Tools, SREs, Parameter Definitions, Data Windows, Documents) so they can be reconciled together via /deploy and addressed at runtime by (stage, logical_name). |
| `GET` | [/stage/{stage_id}](/docs/GET/stage/{stage_id}) | Private | Retrieve a stage by ID. |
| `POST` | [/stage/{stage_id}](/docs/POST/stage/{stage_id}) | Private | Update an existing stage. Renaming a stage updates its name in place; resources deployed to this stage are unaffected and continue to be reconciled by stage_id. |
| `DELETE` | [/stage/{stage_id}](/docs/DELETE/stage/{stage_id}) | Private | Delete a stage. Requires `mode` in the body: 'destroy' wipes every child resource alongside the stage; 'detach' strips the stage binding from each child (turning them back into dashboard-managed resources) and then deletes the stage record. There is no default — the field is required so the destructive choice is always explicit. |
| `GET` | [/stages](/docs/GET/stages) | Private | List all stages for the user's organization. |
| `GET` | [/stage/{stage_id}/manifest](/docs/GET/stage/{stage_id}/manifest) | Private | Export a stage's current resources as a stage-agnostic `ajentify.json` manifest. The returned body has only `tools`, `sres`, and `agents` — the target stage is supplied separately on the deploy request envelope, so the same manifest can be re-deployed into a different stage to promote it. Deploying the exported manifest back into the source stage is a no-op. |

## Deploy

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/deploy](/docs/POST/deploy) | Private | Reconcile a stage's resources to match the submitted manifest. The request wraps a stage-agnostic `manifest` body together with the target `stage` (and optionally `org_id`); the same manifest can be promoted between stages by re-deploying with a different `stage`. Creates the stage if it does not exist; creates / updates / deletes Parameter Definitions, Tools, SREs, and Agents to converge to the desired state. Logical names (the keys in each map) are stable identifiers within the stage and are used as the reconciliation key. Resource IDs are server-managed and never appear in the manifest. Idempotent — re-deploying the same request is a no-op. |
| `POST` | [/deploy/plan](/docs/POST/deploy/plan) | Private | Dry-run version of POST /deploy. Validates the request, computes the plan that would be applied to the named stage, and returns it without making any changes. Useful for CI / pre-merge review. |

## Org Contexts

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/org-contexts](/docs/GET/org-contexts) | Private | List API-key-owned and public contexts in an organization for the admin Contexts inspector. Excludes contexts owned by individual Cognito users. |

## Scrape Page

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/scrape-page/{link}](/docs/GET/scrape-page/{link}) | Private | Scrape content from a web page URL |

## Job

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/job/{job_id}](/docs/GET/job/{job_id}) | Private | Get the status and results of an async job |

## Data Window

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/data-window](/docs/POST/data-window) | Private | Create a data window for providing real-time cached data to agents |
| `GET` | [/data-window/{data_window_id}](/docs/GET/data-window/{data_window_id}) | Private | Retrieve a data window by ID |
| `POST` | [/data-window/{data_window_id}](/docs/POST/data-window/{data_window_id}) | Private | Update a data window's content or metadata |
| `DELETE` | [/data-window/{data_window_id}](/docs/DELETE/data-window/{data_window_id}) | Private | Delete a data window |
| `GET` | [/data-windows](/docs/GET/data-windows) | Private | List all data windows for the user |

## API Key

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/generate-api-key](/docs/POST/generate-api-key) | Private | Generate an API key for programmatic access or client-side WebSocket streaming |
| `GET` | [/api-keys](/docs/GET/api-keys) | Private | List all API keys for an organization |
| `POST` | [/revoke-api-key](/docs/POST/revoke-api-key) | Private | Revoke an API key by marking it as invalid |

## JSON Document

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/json-document](/docs/POST/json-document) | Private | Create a JSON document for agent memory and structured data storage |
| `GET` | [/json-document/{document_id}](/docs/GET/json-document/{document_id}) | Public | Retrieve a JSON document by ID |
| `POST` | [/json-document/{document_id}](/docs/POST/json-document/{document_id}) | Private | Update a JSON document. Pass `stage_id` and `logical_name` together to attach this document to a stage so it appears in /deploy manifests; pass both as null to detach. |
| `DELETE` | [/json-document/{document_id}](/docs/DELETE/json-document/{document_id}) | Private | Delete a JSON document |
| `POST` | [/json-document/{document_id}/set](/docs/POST/json-document/{document_id}/set) | Public | Set a value at a specific path in a JSON document |
| `POST` | [/json-document/{document_id}/add](/docs/POST/json-document/{document_id}/add) | Public | Add an item to a list at a specific path |
| `POST` | [/json-document/{document_id}/delete](/docs/POST/json-document/{document_id}/delete) | Public | Delete a value at a specific path |
| `GET` | [/json-document/{document_id}/value](/docs/GET/json-document/{document_id}/value) | Public | Get a value at a specific path |
| `GET` | [/json-document/{document_id}/shape](/docs/GET/json-document/{document_id}/shape) | Public | Get the shape/schema of a JSON document |
| `GET` | [/json-documents](/docs/GET/json-documents) | Private | List all JSON documents for the user |

## Tool Response

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/on-tool-call-response](/docs/POST/on-tool-call-response) | Private | Submit a response for an async tool call |

## InteliSort

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/inteli-sort](/docs/POST/inteli-sort) | Private | Sort items using LLM-powered pairwise comparison with a tournament bracket algorithm |

## Models

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/models](/docs/GET/models) | Private | List all available LLM models and their pricing |

## Guides

| Guide | Description |
|-------|-------------|
| [Data Usage Policy](/docs/data-usage-policy) | How we handle your data, and what our LLM providers do with it |
| [Authenticated Endpoints](/docs/auth-endpoints) | How to authenticate API requests |
| [Async Callbacks](/docs/async-callbacks) | Receiving responses via webhook callbacks |
| [Data Windows](/docs/data-windows-feature) | Real-time cached data for agents |
| [Client-Side Tools](/docs/ClientSideTools) | Tools that execute in the client |
| [Message Control](/docs/message-control-endpoints) | Fine-grained control over message generation and storage |
| [Prompt Arguments](/docs/prompt-arguments) | Dynamic prompt templating |
| [Initialize Tools](/docs/initialize-tools) | Pre-populating context with tool responses |
| [Async Tools](/docs/async-tools) | Tools with asynchronous execution |
| [Terminating Tool Calls](/docs/terminating-tool-calls) | Autonomous agent execution |
| [Memory Window](/docs/memory-window) | Context memory management |
| [WebSocket API](/docs/WEBSOCKET_API) | Real-time token streaming |
| [Client API Keys](/docs/api-keys) | Secure WebSocket connections |
| [Ajentify Testing](/docs/ajentify-testing) | Test agents with simulated conversations and LLM-powered assessments |
| [Prompt Auditing Principles](/docs/prompt-auditing-principles) | Audit system prompts against 11 quality principles |
| [AjDK Manifest JSON Schema](/docs/manifest-schema.json) | Canonical Draft 2020-12 schema for `ajentify.json`. Reference via `$schema` in your manifest for editor autocomplete. |