Developers / Agents
Add a web page or site to an agent
https://api.echonova.ai/v1/agents/{agentId}/knowledge/webAdds 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
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Path parameters
The agent id, as GET /v1/agents returned it.
Request body
application/json
A public https URL. Private, loopback and link-local addresses and URLs with a user name or password are refused.
The source name. Leave it out to use the URL.
single_url reads one page; website follows links from it.
For a website: how many links deep to follow.
For a website: the most pages to read.
Response
200 application/json Every response uses this envelope.
The result.
The folder or source id.
The name. A web source shows its host and path only.
folder, file or web.
The indexing status of a source; null for a folder.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. agentId or sessionId is not a 24-character hexadecimal id.
Fix. Use the id exactly as GET /v1/agents or the conversations list returned it.
When. url is not an https URL, or points at a loopback, private or link-local address.
Fix. Send a public https URL.
When. url is over 2000 characters.
Fix. Send a shorter URL.
When. The URL carries a user name or password.
Fix. Send the URL without them; private pages cannot be read.
When. The knowledge source name is over 200 characters.
Fix. Send a shorter name.
When. type is any other value.
Fix. Send single_url or website, or leave it out for single_url.
When. depth is above 3, or below 1 (the message then names the lower bound).
Fix. Send a depth from 1 to 3.
When. maxUrls is above 50, or below 1 (the message then names the lower bound).
Fix. Send maxUrls from 1 to 50.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace balance cannot cover the charge for this call; nothing ran and nothing was charged.
Fix. Add credits to the workspace.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key does not have the agents:write scope.
Fix. Edit the key and give it the agents:write scope, or use another key.
When. The member who created the key has left the workspace, or no longer has both the Manage agents and Manage developer API permissions. It is checked on every call.
Fix. Give that member both permissions again, or create a key as a member who has them.
When. The workspace is closed, so knowledge cannot be indexed.
Fix. Contact support to reopen the workspace.
When. The subscription has expired and no bought credits are left, so knowledge cannot be indexed.
Fix. Renew the subscription or buy credits.
When. The agent id is unknown, or the agent belongs to another workspace.
Fix. Use an id from GET /v1/agents with a key of the agent's workspace.
When. The agent is archived. Only duplicate, archive and restore work on an archived agent.
Fix. Restore it with POST /v1/agents/{agentId}/restore, or duplicate it and change the copy.
When. The JSON body of an agent write is over 512 KB; the request is rejected before the API key is checked, so it has no Activity row.
Fix. Send a smaller body; split long knowledge text into several sources.
When. The request has a body whose Content-Type is not application/json.
Fix. Send Content-Type: application/json.
When. The key made more than 20 requests to this endpoint in 60 seconds; a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
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
}