# Ajentify API Documentation

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

## These Docs Are Designed For AI

Every page in this documentation can be read two ways:

- **In your browser** — rendered as HTML for humans
- **By your agent** — returned as clean, structured Markdown

That means your AI agent can explore and understand the Ajentify API on its own.

Start from the index:

```
curl https://api.ajentify.com/docs
```

From there, it can:

- Discover available endpoints and guides
- Follow links to only the sections it needs
- Load documentation incrementally to stay within context

No SDKs. No plugins. No MCP servers.

Just HTTP — and documentation your agent can actually use.

## 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 |
| `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. |

## Auth

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/auth](/docs/POST/auth) | Public |  |

## Create Account

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/create-account](/docs/POST/create-account) | Public |  |

## Verify Code

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/verify-code](/docs/POST/verify-code) | Public |  |

## Resend Code

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/resend-code](/docs/POST/resend-code) | Public |  |

## Login

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/login](/docs/POST/login) | Public |  |

## Reset Password

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/reset-password](/docs/POST/reset-password) | Public |  |

## Set New Password

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/set-new-password](/docs/POST/set-new-password) | Public |  |

## Refresh

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/refresh](/docs/POST/refresh) | Public |  |

## User

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/user](/docs/POST/user) | Private | Create a new user account |
| `GET` | [/user](/docs/GET/user) | Private | Get the authenticated user's profile |
| `DELETE` | [/user](/docs/DELETE/user) | Private | Delete the authenticated user's account |

## Organization

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/organization](/docs/POST/organization) | Private | Create a new organization |

## 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. |

## Chat Page

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/chat-page](/docs/POST/chat-page) | Private | Create an embeddable chat page |
| `POST` | [/chat-page/{chat_page_id}](/docs/POST/chat-page/{chat_page_id}) | Private | Update a chat page's configuration |
| `GET` | [/chat-page/{chat_page_id}](/docs/GET/chat-page/{chat_page_id}) | Public | Retrieve a chat page by ID |
| `DELETE` | [/chat-page/{chat_page_id}](/docs/DELETE/chat-page/{chat_page_id}) | Private | Delete a chat page |
| `GET` | [/chat-pages](/docs/GET/chat-pages) | Private | List all chat pages for the user |

## 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 |

## Chat Bot

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/chat-bot/{chat_page_id}](/docs/GET/chat-bot/{chat_page_id}) | Public | Get the embeddable chat bot JavaScript widget |

## 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 |

## Integration

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `POST` | [/integration](/docs/POST/integration) | Private | Create a new integration |
| `GET` | [/integration/{integration_id}](/docs/GET/integration/{integration_id}) | Private | Retrieve an integration by ID |
| `POST` | [/integration/{integration_id}](/docs/POST/integration/{integration_id}) | Private | Update an integration |
| `DELETE` | [/integration/{integration_id}](/docs/DELETE/integration/{integration_id}) | Private | Delete an integration |
| `GET` | [/integrations](/docs/GET/integrations) | Private | List all integrations for the user |

## 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 |

## Usage

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| `GET` | [/usage](/docs/GET/usage) | Private | Get token usage statistics for the organization |

## 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. |