# Agents API

Tradly AI Studio agents combine a prompt, persona, user prompts, tools, versions, and optional knowledge sources into a deployable shopping or support assistant.

## Base URL

```text
https://api-eu-aisearch.tradly.app
```

Replace the host with your environment when using a different region or deployment.

## Authentication

Send a tenant user JWT as a bearer token:

```http
Authorization: Bearer <JWT>
```

Agent routes are tenant-scoped. Supply `tenant_id` using the same header, query, or body convention configured for your environment. Never expose provisioning tokens or claim secrets in browser code.

The `agentRef` path parameter accepts either the numeric agent `id` or its string `unique_id`.

## Agent lifecycle

1. Create an agent with an optional initial version.
2. Add or publish versions and select the default version.
3. Attach URL, file, or text knowledge sources.
4. Poll knowledge status until it becomes `ready` or `failed`.
5. Disable an agent by setting its status to `inactive`.

## Endpoint reference

- [List agents](/docs/agents/list)
- [Create an agent](/docs/agents/create)
- [Get an agent](/docs/agents/detail)
- [Update an agent](/docs/agents/update)
- [Create an agent version](/docs/agents/create-version)
- [Set the default version](/docs/agents/set-default-version)
- [List knowledge sources](/docs/agents/knowledge-list)
- [Add URL knowledge](/docs/agents/knowledge-url)
- [Add file knowledge](/docs/agents/knowledge-file)
- [Add text knowledge](/docs/agents/knowledge-text)
- [Update knowledge status](/docs/agents/knowledge-status)
- [Delete a knowledge source](/docs/agents/knowledge-delete)

## Public trial creation

AI Studio also exposes a server-side public flow at `POST /api/public/agents/create` on the AI Studio web app. It accepts a website URL or agent prompt, applies rate limiting, creates an upstream agent, attaches generated knowledge, and returns a short-lived claim token.

This public flow is different from the authenticated `POST /v1/agents` API. Keep upstream credentials server-side and use the public route when creating an agent from an unauthenticated landing page.