API DocsReady Agents

Ready Agents

Ready-to-use OpenAI-compatible agents with scoped access to knowledge bases, skills, and connected apps.

The ready-to-use RAG agent follows the OpenAI Chat Completions format and adds multiple knowledge-base IDs plus optional skill IDs.

POST/api/v1/agents/rag/chat/completions

Explicit asset access

The agent can access only the IDs sent in this request. Knowledge-base tools are always available. Skill tools are attached only when skill_ids is not empty.

Request body

Common sampling and output parameters are supported. The agent owns tool orchestration: tools, tool_choice, functions, and function_call are not accepted, and n is limited to 1. Asset fields enforce the agent scope on the server.

Parameter	Type	Default	Description
`model`required	`string`	-	A model from the anymize model catalog.
`messages`required	`array`	-	OpenAI-compatible messages in conversation order.
`knowledge_base_ids`required	`uuid[]`	-	One to eight accessible knowledge-base IDs whose processing is complete.
`skill_ids`	`uuid[]`	-	Optionally, up to eight accessible skill IDs. No skill tool is exposed without IDs.
`stream`	`boolean`	`false`	Returns an OpenAI-compatible SSE response when true.

Complete example

Existing OpenAI clients need only a different base URL and extra_body for the asset IDs.

1from openai import OpenAI
2
3client = OpenAI(
4    api_key="YOUR_API_KEY",
5    base_url="https://app.anymize.ai/api/v1/agents/rag",
6)
7
8response = client.chat.completions.create(
9    model="auto",
10    messages=[
11        {"role": "user", "content": "Summarize the termination rules."}
12    ],
13    extra_body={
14        "knowledge_base_ids": ["aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"],
15        "skill_ids": ["bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"],
16    },
17)
18
19print(response.choices[0].message.content)
20print(response.citations)

What the agent does

It searches only the selected knowledge bases and retrieves exact passages.

It loads only explicitly selected skills and their bundle files when needed.

It writes the answer and adds protected, clickable links to every passage it uses.

Internal tool calls stay hidden. Streaming returns normal OpenAI SSE chunks followed by the deduplicated citations list.

Connected Research Agent

The ready Connected Research Agent reads only from the connected apps selected through connector_ids. It discovers their tools progressively and keeps the model context small.

POST/api/v1/agents/connected-research/chat/completions

Intentionally read-only

This stateless agent removes write tools in code. Sending, creating, updating, and deleting will require a separate durable approval flow.

Discover available asset IDs

The paginated asset catalog returns the exact knowledge bases, skills, and connector references the authenticated user may select. Use offset and limit until has_more is false for every asset family. Built-ins use values such as provider:microsoft; custom MCPs use custom:UUID.

GET/api/v1/agents/assets

1curl "https://app.anymize.ai/api/v1/agents/assets?offset=0&limit=100" \
2  -H "Authorization: Bearer YOUR_API_KEY"

Request body

Parameter	Type	Default	Description
`model`required	`string`	-	Connector access requires waterfall-2.0 so private app data stays inside the protected anymize environment.
`messages`required	`array`	-	OpenAI-compatible messages in conversation order.
`connector_ids`required	`string[]`	-	One to eight connector references from GET /api/v1/agents/assets.
`skill_ids`	`uuid[]`	-	Optionally, up to eight accessible skill IDs. No skill tool is exposed without IDs.
`knowledge_base_ids`	`uuid[]`	-	Optionally, up to eight processed knowledge bases for internal evidence and clickable citations.
`stream`	`boolean`	`false`	Returns an OpenAI-compatible SSE response when true.

Customer briefing from calendar and CRM

The agent sees only Microsoft 365 and HubSpot from this request. Other connected apps remain invisible.

1from openai import OpenAI
2
3client = OpenAI(
4    api_key="YOUR_API_KEY",
5    base_url="https://app.anymize.ai/api/v1/agents/connected-research",
6)
7
8response = client.chat.completions.create(
9    model="waterfall-2.0",
10    messages=[
11        {"role": "user", "content": "Summarize today's customer meetings and the latest CRM activity."}
12    ],
13    extra_body={
14        "connector_ids": [
15            "provider:microsoft",
16            "provider:hubspot",
17        ]
18    },
19)
20
21print(response.choices[0].message.content)

Progressive tool disclosure

The server verifies every connector ID, compliance rule, and enabled capability before the first model call.

The model initially sees one dispatcher and loads only the apps and tools needed for the task.

Authorization and connection state are checked again before every call. Unknown or mutating tools remain removed.

Clickable anymize chunk citations are produced for knowledge-base results. Connector results may provide native source links, but they are not emitted as internal chunk citations.

Workspace Agent

The Workspace Agent combines knowledge bases, skills, and connected apps in one OpenAI-compatible request. Each asset family is attached only when its IDs are provided.

POST/api/v1/agents/workspace/chat/completions

One agent, explicit capabilities

At least one asset ID is required. Skills add instructions, never permissions. When connectors are selected, the agent is read-only and requires waterfall-2.0.

Request body

Parameter	Type	Default	Description
`model`required	`string`	-	Any supported model without connectors. With connector_ids, waterfall-2.0 is required.
`messages`required	`array`	-	OpenAI-compatible messages in conversation order.
`knowledge_base_ids`	`uuid[]`	-	Optionally, up to eight processed knowledge bases for internal evidence and clickable citations.
`skill_ids`	`uuid[]`	-	Optionally, up to eight accessible skill IDs. No skill tool is exposed without IDs.
`connector_ids`	`string[]`	-	Optionally, up to eight namespaced connector references. No connector tool is attached without IDs.
`stream`	`boolean`	`false`	Returns an OpenAI-compatible SSE response when true.

Ready recipes

The same secure building blocks create several specialized agents. Change only the IDs and task.

Account Briefing

Combines calendar, CRM, internal policies, and a relevant skill into an evidence-backed customer briefing.

Literature Review

Combines Elicit research with internal knowledge bases and clickable evidence.

SQL Analyst

Analyzes PostgreSQL or MySQL through strictly read-only tools without changing data.

1from openai import OpenAI
2
3client = OpenAI(
4    api_key="YOUR_API_KEY",
5    base_url="https://app.anymize.ai/api/v1/agents/workspace",
6)
7
8response = client.chat.completions.create(
9    model="waterfall-2.0",
10    messages=[{"role": "user", "content": "Prepare a briefing for my next customer meeting and cite internal claims."}],
11    extra_body={
12        "knowledge_base_ids": ["aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"],
13        "skill_ids": ["bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"],
14        "connector_ids": ["provider:microsoft", "provider:hubspot"],
15    },
16)
17
18print(response.choices[0].message.content)
19print(response.citations)

Skills MCP

The hosted Skills MCP lets external MCP clients read accessible anymize skills. Together with the Knowledge MCP, an agent can use both asset types.

POST/api/mcp/skills

API key required

The MCP endpoint accepts Authorization: Bearer only. Session cookies are intentionally not used.

Connect both asset servers

Configure knowledge bases and skills as separate MCP servers so the client can distinguish their permissions and tool calls.

1{
2  "mcpServers": {
3    "anymize-knowledge": {
4      "url": "https://app.anymize.ai/api/mcp",
5      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
6    },
7    "anymize-skills": {
8      "url": "https://app.anymize.ai/api/mcp/skills",
9      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
10    }
11  }
12}

Available tools

Parameter	Type	Default	Description
`list_skills`	`tool`	-	Lists the skills the API-key owner is allowed to access.
`get_skill`	`tool`	-	Loads metadata, instructions, and the file list for one skill by UUID.
`read_skill_file`	`tool`	-	Reads one bundle file from an accessible skill through a safe relative path.

Inside the ready RAG agent, these tools are further restricted to skill_ids from that request. Automatically active project or team skills are not added silently.

Clickable citations

Every RAG result contains chunk_id and citation_url. The link opens the source in anymize and highlights the exact cited passage.

GET/api/v1/chunks/{chunk_id}

Citation contract

The chunk UUID identifies a passage in the current index. Reindexing can assign a new UUID. citation_id and job_id remain available for existing integrations.

200Clickable citations

{
  "chunk": {
    "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
    "job_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
    "knowledge_base_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "content": "The notice period is three months to the end of a quarter.",
    "chunk_index": 7,
    "source": "vertrag.pdf",
    "page": 4,
    "section": "Laufzeit",
    "citation_url": "https://app.anymize.ai/chunk/cccccccc-cccc-4ccc-8ccc-cccccccccccc"
  }
}

Open the highlighted source

Open citation_url directly from a Markdown answer. After sign-in, anymize loads the document, moves to the passage, and highlights it.

Access stays protected

The metadata endpoint verifies ownership or accepted knowledge-base membership and otherwise returns 404. An anonymized document never falls back to clear text.