---
title: "Add a website to the Knowledge"
method: POST
path: "/api/agent-sources"
tags: ["agent_sources"]
---

# Add a website to the Knowledge

`POST /api/agent-sources`

## Request

- Base URL: `https://beta.getsales.io/unibox/v1`
- URL: `https://beta.getsales.io/unibox/v1/api/agent-sources`
- Auth: HTTP bearer and API key in header `Team-SID`

Add a website to the Knowledge: its start address, the scope under it (the address's own path unless given), how often it is read again (weekly unless said, or daily) and how to read it (instruction, up to 600 chars; suggest_agent_source_instruction writes one from its first pages). Nothing is read yet: parse_agent_source starts the read. A file is uploaded in the app.

Contract:
- MCP tool `create_agent_source`, registry package `mcp.unibox/agent_sources`, mount `unibox.knowledge`.
- Operation `create`, response envelope `create`.
- Flags: none.

## Request body

- CreateAgentSourceRequest: Request body of `create_agent_source`.
  - `agent_sid` string: The AI SDR it is made for (ub_ag_…, block 10, 2026-10-30); left out, the team's default agent.
  - `kind` 'website': website, the only kind a call adds (a file is uploaded in the app); may be left out.
  - `url` string, required: The start address (https when no scheme is given; a public host). The pages under it are read.
  - `scope` string, nullable: The path the pages are read under ("/docs"); the address's own path unless given, / for the whole site.
  - `refresh` 'weekly' | 'daily', nullable: How often it is read again by itself: weekly unless said, or daily.
  - `instruction` string, nullable: How to read it, in plain words: what the document is, what to read out (the questions a lead would ask), what to skip, how exact. Up to 600 chars.

## Response `200`

`create` success envelope.

- CreateAgentSourceResponse
  - `success` true, required
  - `operation` 'create', required
  - `item` object, required
    - `sid` string, required: Knowledge document sid (ub_as_…).
    - `team_sid` string, required: Owning team (ts_tm_…, external - gs.service.id).
    - `agent_sid` string, required: The team's agent (ub_ag_…).
    - `kind` 'file' | 'website', required: file: a file the team uploaded; website: a start address and the pages under it (a help center is a website).
    - `title` string, required: The name the list shows: a file's name until renamed, a website's host and path.
    - `status` 'reading' | 'read' | 'failed', required: reading while a parse runs (progress says page n of m), read once a parse finished (its answers wait for the OK or are in Knowledge), failed with the reason in failure.
    - `instruction` string, nullable, required: How the parse reads it, in the person's words, up to 600 chars: what to read out, what to skip, how exact. Suggested from the first pages (suggest_agent_source_instruction), edited by the person; null until one is written.
    - `file` object, nullable, required: A file's file; null for a website.
      - `name` string, required: The file's name as uploaded.
      - `format` 'pdf' | 'docx' | 'txt' | 'md', required
      - `mime` string, required: Its media type as uploaded.
      - `bytes` integer, required: Its size, 20 MB at most.
      - `pages` integer, nullable, required: Its pages (a PDF's, a Word file's as Word counted them); null for a text file.
    - `website` object, nullable, required: A website's address, scope, refresh and pages; null for a file.
      - `url` string, required: The start address.
      - `scope` string, required: The path under which pages are read; / for the whole site.
      - `refresh` 'weekly' | 'daily', required: How often it is read again by itself.
      - `pages` integer, nullable, required: How many pages the last read took; null until read.
    - `progress` object, required: How far the parse got: page n of m ("Reading, page 9 of 22"); 0 of 0 before the pages are known.
      - `done` integer, required
      - `total` integer, required
    - `failure` object, nullable, required: Why the parse gave up; null unless failed.
      - `reason` 'unreadable' | 'no_text' | 'too_large' | 'website_unreachable' | 'nothing_found' | 'model_failed', required
      - `message` string, required: What to do, in the words the list shows.
    - `read_at` string, nullable, required: ISO 8601 UTC of the last parse that finished; null until then.
    - `next_refresh_at` string, nullable, required: A website: ISO 8601 UTC of its next read by itself; null for a file.
    - `created_by` object, required: Who added it.
      - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required
      - `actor_sid` string, nullable, required
      - `team_sid` string, required
      - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job.
      - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path.
      - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise.
      - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract.
      - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write.
      - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row.
    - `created_at` string, required: ISO 8601 UTC.
    - `updated_at` string, required: ISO 8601 UTC.
  - `already_exists` boolean, required
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/revisions/8f1bc317897f?raw)