---
title: "Parse a document into answers"
method: POST
path: "/api/agent-sources/{sid}/parse"
tags: ["agent_sources"]
---

# Parse a document into answers

`POST /api/agent-sources/{sid}/parse`

## Request

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

Read a Knowledge document (Parse from document): its pages are read as the instruction says (one given here is written on the document first), split into passages, the questions and answers extracted (model calls metered as drafts), each compared with Knowledge: new, already_there, says_otherwise; a document read before compares with its own answers first. The record rides result.parse and waits (get_agent_source_parse) for apply_agent_source_parse. 409 source_reading while a parse runs.

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

## Path parameters

- `sid` string, required: Knowledge document sid (ub_as_…).

## Request body

- ParseAgentSourceRequest: Request body of `parse_agent_source`.
  - `instruction` string, nullable: The instruction to read by, written on the document first when given; else the document's own.

## Response `200`

`action` success envelope.

- ParseAgentSourceResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` object, nullable, 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.
  - `result` object, required
    - `parse` object, required: The parse record opened (queued, or further when the queue ran it at once): get_agent_source_parse reads where it stands and what it found.
      - `sid` string, required: Parse record sid (ub_ps_…).
      - `team_sid` string, required: Owning team (ts_tm_…, external - gs.service.id).
      - `agent_sid` string, required: The team's agent (ub_ag_…).
      - `source_sid` string, required: The document read (ub_as_…).
      - `kind` 'parse' | 'again' | 'refresh', required: parse: a first read, compared with every answer the agent has; again: Read it again or a replaced file, compared with the document's own answers first; refresh: a website's scheduled read, the same comparison.
      - `status` 'queued' | 'reading' | 'found' | 'applied' | 'failed' | 'discarded', required: queued for the job; reading (step says which); found (the answers wait for the OK); applied (what the person picked is in Knowledge; a read again that found everything as it was applies itself); failed (failure says why); discarded (closed with nothing added).
      - `instruction` string, nullable, required: The instruction this parse read by.
      - `step` 'reading' | 'splitting' | 'extracting' | 'comparing', nullable, required: Where a running parse stands: reading, splitting, extracting, comparing; null otherwise.
      - `steps` object, required: What it did, as the modal shows it; a step not reached is absent.
        - `pages` object: The pages read, skipped on the instruction's word, and in all.
          - `read` integer, required
          - `skipped` integer, required
          - `total` integer, required
        - `passages` integer: The passages split by heading.
        - `questions` integer: The questions found with their answers.
        - `compared` object: The rows per state.
          - `new` integer, required
          - `already_there` integer, required
          - `says_otherwise` integer, required
          - `unchanged` integer, required
          - `gone` integer, required
        - `applied` object: What apply did: answers added, written over, removed.
          - `added` integer, required
          - `updated` integer, required
          - `removed` integer, required
      - `found` object[], required: The answers found, each with its state against Knowledge; empty until the comparison finished (and on the include of search_agent_sources).
        - `id` integer, required: The row's id within the parse, from 1: what apply names.
        - `question` string, required: The question as a lead would ask it, up to 500 chars.
        - `phrasings` string[], required: Other ways a lead would ask it, up to twelve.
        - `answer` string, required: The answer in the document's words, up to 1200 chars.
        - `page` integer, nullable, required: The page it was read from (a website's page ordinal); null for a text file.
        - `url` string, nullable, required: A website page's address; null for a file.
        - `passage_from` integer, nullable, required: The passage's start offset in its page's text.
        - `passage_to` integer, nullable, required: The passage's end offset.
        - `passage` string, nullable, required: The passage it was read from, up to 1200 chars.
        - `state` 'new' | 'already_there' | 'says_otherwise' | 'unchanged' | 'gone', required: new: nothing in Knowledge answers it (comes checked); already_there: an answer with the same meaning exists (comes unchecked); says_otherwise: an answer exists and differs (Keep ours or Use the new one); unchanged: a read again found the document's own answer as it was (its sid and reads kept); gone: an earlier answer of the document the read again did not find (listed to remove).
        - `similarity` number, nullable, required: How near the existing answer's question is, (1 + cosine) / 2; null on a new row.
        - `existing` object, nullable, required: The existing answer the row was compared with; null on a new row.
          - `sid` string, required: The existing answer (ub_an_…).
          - `question` string, required: Its question.
          - `answer` string, required: Its answer.
          - `source_kind` string, required: document or manual.
          - `source_sid` string, nullable, required: Its document (ub_as_…) when read from one.
          - `source_title` string, nullable, required: That document's title.
          - `page` integer, nullable, required: That document's page.
      - `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 modal shows.
      - `read_at` string, nullable, required: ISO 8601 UTC when the comparison finished; null until then.
      - `applied_at` string, nullable, required: ISO 8601 UTC when the answers were taken in; null until then.
      - `applied_by` object, nullable, required: Who took them in; null on a read that applied itself.
        - `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_by` object, required: Who opened the parse; the system on a website's refresh.
        - `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.
  - `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)