API Reference

Reference links

Attach URLs to an agent and have them crawled into its knowledge base. Every endpoint here is scoped to one agent.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 9
Scopes: agents:readagents:write

POST/agents/:id/reference-links

Attach one or more URLs and queue their first crawl.

Attach reference links

Returns immediately with each link crawl_state = queued: a fifty-page crawl with embedding does not fit inside an HTTP request, and there is nothing to review until it has run. All or nothing. One bad URL rejects the whole request with a message naming it, rather than creating the others and leaving you to work out which ones landed.

Path & Query

idstringrequired
The agent the link belongs to.

Request body

linksarrayrequired
The links to attach. At least one, at most ten per request, and an agent carries at most ten in total.
links[].urlstringrequired
An http or https URL. Normalised before it is stored: tracking parameters and the fragment are dropped, the host is lowercased. Two spellings of the same page therefore count as one link.
links[].crawl_modestringoptional
page (default) reads that one URL. site also follows its internal links, bounded by the global page and depth limits.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

409Link already attached

This agent already has a link for one of these URLs. Because URLs are normalised first, /docs and /docs?utm_source=x collide here.

The error names the URLs. Drop them from the request, or re-crawl the existing link instead.

422Malformed URL

A URL is not http/https, carries credentials, contains control characters, or exceeds 2048 characters. The same request also fails if it lists one page twice.

The message names the offending URL. Fix it and resend the whole list.

422Too many links

An agent can carry at most ten reference links, and the request would take it past that.

Delete links you no longer need, or split the pages across agents.

Request

json

curl -X POST https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      { "url": "https://docs.example.com/", "crawl_mode": "site" },
      { "url": "https://example.com/pricing" }
    ]
  }'

201 Response

json

[
  {
    "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
    "url": "https://docs.example.com/",
    "crawl_mode": "site",
    "crawl_state": "queued",
    "last_crawl_at": null,
    "last_crawl_error_code": null,
    "last_crawl_error_detail": null,
    "next_crawl_at": "2026-08-31T12:18:07.902114Z",
    "pages": { "in_service": 0, "awaiting_review": 0, "rejected": 0, "flagged": 0 }
  },
  {
    "id": "9d2f0a71-1c4e-4a6b-9f31-2b8a5c7e0d14",
    "url": "https://example.com/pricing",
    "crawl_mode": "page",
    "crawl_state": "queued",
    "last_crawl_at": null,
    "last_crawl_error_code": null,
    "last_crawl_error_detail": null,
    "next_crawl_at": "2026-08-31T12:18:07.902114Z",
    "pages": { "in_service": 0, "awaiting_review": 0, "rejected": 0, "flagged": 0 }
  }
]

GET/agents/:id/reference-links

Every link on the agent, with a breakdown of its pages.

List reference links

pages.flagged is the count worth watching: it is the number of pages holding an extraction the crawler refused to publish, recomputed on every read. crawl_state answers a different question, whether the last crawl worked. So a page whose extraction collapsed leaves the link ready.

Path & Query

idstringrequired
The agent the link belongs to.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

Request

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

[
  {
    "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
    "url": "https://docs.example.com/",
    "crawl_mode": "site",
    "crawl_state": "ready",
    "last_crawl_at": "2026-08-31T12:19:22.471531Z",
    "last_crawl_error_code": null,
    "last_crawl_error_detail": null,
    "next_crawl_at": "2026-09-01T12:19:22.471531Z",
    "pages": {
      "in_service": 1,
      "awaiting_review": 0,
      "rejected": 0,
      "flagged": 1
    }
  }
]

GET/agents/:id/reference-links/:link_id

The same shape as the list, for a single link.

Get one reference link

Useful for polling after attaching a link or forcing a re-crawl: watch crawl_state leave queued, then crawling.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.

Request

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
  "url": "https://docs.example.com/",
  "crawl_mode": "site",
  "crawl_state": "ready",
  "last_crawl_at": "2026-08-31T12:19:22.471531Z",
  "last_crawl_error_code": null,
  "last_crawl_error_detail": null,
  "next_crawl_at": "2026-09-01T12:19:22.471531Z",
  "pages": {
    "in_service": 1,
    "awaiting_review": 0,
    "rejected": 0,
    "flagged": 1
  }
}

GET/agents/:id/reference-links/:link_id/pages

What the crawl extracted, anomalies first.

Preview a link's pages

Sorted server-side so every client sees the same order: pages holding a candidate first, then anything awaiting review, and within each group the shortest extraction first, because a page that came back nearly empty is the likeliest bad scrape. excerpt is the first 600 characters of the markdown. candidate is present only when a re-crawl held an extraction back; it carries the size before and after, and the title the new version would take.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.

Request

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/pages \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "link_id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
  "pages": [
    {
      "id": "7db1d521-4546-4a3a-b271-9a7ab9e52ce7",
      "source_url": "https://docs.example.com/pricing",
      "title": "Pricing",
      "status": "completed",
      "size_bytes": 7178,
      "chunk_count": 4,
      "excerpt": "# Pricing\n\nEvery plan includes unlimited agents...",
      "candidate": {
        "at": "2026-08-31T12:19:22.471531Z",
        "title": "Pricing",
        "size": 501,
        "previous_size": 7178
      }
    },
    {
      "id": "44585690-6c50-4713-93e0-0205132470b1",
      "source_url": "https://docs.example.com/",
      "title": "Documentation",
      "status": "completed",
      "size_bytes": 15886,
      "chunk_count": 9,
      "excerpt": "# Documentation\n\nStart here...",
      "candidate": null
    }
  ]
}

GET/agents/:id/reference-links/:link_id/pages/:doc_id

The full text of a single page, and the held-back version when there is one.

Read one crawled page

The pages list carries excerpts; this returns the page in full. When a re-crawl held a shrunken version back, candidate carries that version's markdown alongside the one still being served, so you can compare the two texts rather than two byte counts before accepting or leaving it.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.
doc_idstringrequired
The page, from the id returned by the preview endpoint.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.

Request

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/pages/doc-uuid \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "7db1d521-4546-4a3a-b271-9a7ab9e52ce7",
  "source_url": "https://docs.example.com/pricing",
  "title": "Pricing",
  "status": "completed",
  "size_bytes": 7178,
  "chunk_count": 4,
  "content_hash": "9f2c1b7e...",
  "markdown": "# Pricing\n\nEvery plan includes unlimited agents...",
  "candidate": {
    "at": "2026-08-31T12:19:22.471531Z",
    "title": "Pricing",
    "size": 501,
    "previous_size": 7178,
    "markdown": "# Pricing\n\nContact sales."
  }
}

POST/agents/:id/reference-links/:link_id/approve

Put the link's pending pages into service, minus the ones you exclude.

Approve a link's pages

One endpoint rather than an approve and a reject pair: it mirrors what a reviewer does, untick then confirm, it is a single transaction, and it leaves no state where half the link is live. An excluded page becomes rejected and loses its chunks, so the index carries nothing that will never be served; the decision is remembered, and a later re-crawl re-proposes the page only if the site changed it.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.

Request body

excludearrayoptional
Page ids to turn down, from the preview endpoint. Omit or send an empty list to approve everything.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.

Request

json

curl -X POST \
  https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/approve \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exclude": ["doc-uuid-you-reject"] }'

200 Response

json

{
  "approved": 8,
  "rejected": 1
}

POST/agents/:id/reference-links/:link_id/pages/:doc_id/accept-candidate

Publish the extraction a re-crawl held back on one page.

Accept a held candidate

A re-crawl that comes back with a fraction of the text keeps serving what it had and stores the new extraction aside. This publishes it: the page is re-chunked and re-embedded, and it never leaves service while that happens. Its own route rather than a flag on approve, because approve is link-scoped and its exclude list means "turn this page down". A page left in would have to mean "replace what is live with this new text". There is deliberately no counterpart that dismisses a candidate: the hold says the source is serving a page that lost most of its text, which stays true until the site changes, and clears itself when it does.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.
doc_idstringrequired
The page, from the id returned by the preview endpoint.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.

404Page not found on this link

No page with that id belongs to this link.

Take the id from the preview endpoint.

409Nothing held for review

This page has no candidate. Either it never had one, or a later pass resolved it: a healthy re-crawl clears the hold on its own.

Re-read the preview: if candidate is null there is nothing to publish.

Request

json

curl -X POST \
  https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/pages/doc-uuid/accept-candidate \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "7db1d521-4546-4a3a-b271-9a7ab9e52ce7",
  "source_url": "https://docs.example.com/pricing",
  "size_bytes": 501,
  "chunk_count": 1
}

POST/agents/:id/reference-links/:link_id/recrawl

Run a pass now instead of waiting for the schedule.

Force a re-crawl

Returns the link as it stands, before the pass runs. The job id is deterministic, so pressing this while a pass is already queued or running collapses into that one rather than putting two crawls on the same pages.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.

Request

json

curl -X POST \
  https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/recrawl \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
  "url": "https://docs.example.com/",
  "crawl_mode": "site",
  "crawl_state": "ready",
  "last_crawl_at": "2026-08-31T12:19:22.471531Z",
  "last_crawl_error_code": null,
  "last_crawl_error_detail": null,
  "next_crawl_at": "2026-09-01T12:19:22.471531Z",
  "pages": {
    "in_service": 1,
    "awaiting_review": 0,
    "rejected": 0,
    "flagged": 1
  }
}

DELETE/agents/:id/reference-links/:link_id

Remove the link, its pages, and their chunks.

Delete a reference link

Cascades: every document the link produced is deleted along with its vectors, so the agent stops answering from that source immediately. A single page cannot be deleted through the knowledge-base endpoints, because the next crawl would recreate it. Exclude it when approving, or delete the whole link.

Path & Query

idstringrequired
The agent the link belongs to.
link_idstringrequired
The reference link.

Errors

401Missing or invalid API key

The X-API-Key header was absent, malformed, or the key has been revoked.

Send a live key from your dashboard.

403Key lacks the required scope

Reading links needs agents:read; attaching, approving, accepting and deleting need agents:write.

Use a key that carries the scope, or add it to this one.

404Agent not found

No agent with that id exists on your account. Agents are scoped to the key's tenant, so another account's agent reads as absent.

Check the agent id.

404Reference link not found

No link with that id is attached to this agent.

List the agent's links and use an id from the response.