Developers / Agents

Add a web page or site to an agent

POST https://api.echonova.ai/v1/agents/{agentId}/knowledge/web

Adds a public https page, or a site crawled from it (up to 3 links deep and 50 pages), to the workspace knowledge and to this agent. It is read in the background and never re-crawled on a schedule; GET /v1/agents/{agentId}/knowledge shows its status. An empty wallet answers 402. At most 20 calls a minute per key. Needs the agents:write scope on the key. Indexing uses workspace credits and does not count against an API key's credit limit.

Headers

Authorization string Required

Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.

Path parameters

agentId string Required

The agent id, as GET /v1/agents returned it.

Request body

application/json

url string Required

A public https URL. Private, loopback and link-local addresses and URLs with a user name or password are refused.

Up to 2000 characters
name string Optional

The source name. Leave it out to use the URL.

Up to 200 characters
type string Optional

single_url reads one page; website follows links from it.

single_url or websitedefault single_url
depth integer Optional

For a website: how many links deep to follow.

1 to 3
maxUrls integer Optional

For a website: the most pages to read.

1 to 50

Response

200 application/json Every response uses this envelope.

data object

The result.

success boolean

true for a successful call.

statusCode integer

Repeats the HTTP status.

errorMessage string or null

null on success.

Errors

Same envelope, with success false and data null. All errors

POST /v1/agents/{agentId}/knowledge/web

curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/knowledge/web" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/faq"}'

{
  "data": {
    "id": "6653a1b2c3d4e5f6a7b8c9d0",
    "name": "Price list",
    "kind": "file",
    "status": "ready"
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}