PIpipeshub-ai
Connector

Get a record's full parsed content and metadata

Changed on

Retrieve the full parsed content and metadata of a single record — the same content PipesHub's own RAG/chat pipeline uses to answer questions, returned directly instead of via chat.

When to use this vs. the other record endpoints:

  • GET /knowledgeBase/record/{recordId} returns metadata only (name, type, indexing status, size) — no content.
  • GET /knowledgeBase/stream/record/{recordId} returns the original, unparsed file bytes — use it to download/open the source file.
  • This endpoint returns the record's full parsed content as a single plain-text content string (a metadata header, then the block/table text in reading order, then any foreign-key related tables) — use it when you need the record's actual textual/tabular content without downloading and re-parsing the original file yourself.

Typical flow: obtain a recordId from a pipeshub_search hit or a chat citation's recordId, then call this endpoint to read the full content when the search snippet or citation excerpt isn't enough to answer the question.

Reading part of a long record, or a whole Slack thread:

With no query parameters the record is returned up to 140,000 characters (a longer one is cut and marked truncated), which for a pull request with its diffs or a long document is a large response. Pass any of maxChars, startBlock, query or mode for a budgeted read instead: the response stays within maxChars and says how to continue (nextStartBlock, or nextStartRecord for a thread). query makes a record too large for the budget show its most relevant blocks first, with the skipped ranges marked. mode=thread returns every message of the Slack thread the record belongs to, oldest first, as far as the caller may see them. A Slack record in no single thread (several channel messages in one record, or a message without replies) returns itself, then the replies of each thread its messages started; the first page opens with a bracketed note saying which.

Permission scoping:

The requesting user/token must have access to the record; access is verified via the knowledge graph before content is returned — a caller with a valid scope but no access to this specific record gets a 403.

A connected app with a limit: the rendered text names nothing outside the limit beside the record. Its External Parent ID reads N/A for a parent the limit leaves out, and a code file's Path: line is left out unless the limit covers the whole app. Linked records, related tables, a deal's orgs and products, and live Jira parent, epic, sub-task and linked-issue lines appear only for records inside the limit. Web URL is kept, though it can contain folder names.

get/connectors/record/{recordId}/content

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/connectors/record/{recordId}/content
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: /api/v1/oauth2/authorize
      Client credentials
      Token URL: /api/v1/oauth2/token scopes: connector:read

Path parameters

recordIdstring required

Record ID to fetch. Obtain it from a pipeshub_search result (hits[*].recordId) or a chat citation (citations[*].recordId).

Query parameters

maxCharsinteger

Most characters of content to return. Asks for a budgeted read; 40000 when another budgeted-read parameter is given without it.

extract'true' | 'false'

With query, in record mode and without startBlock: return only the passages that answer query, as the model assigned to the reader role (else the default model) copies them out, instead of the record's text. The model is told to copy word for word, and extract.unverifiedLines counts the lines it did not. The response's order is extract, and its extract object names the model and the tokens it used. When the model cannot be reached, the usual read is returned with extract.error set.

startBlockinteger

Read in order from this block: the nextStartBlock of a previous read, or 0 for the top. Takes precedence over query. In thread mode it applies to the record at startRecord; later records are read from their start.

querystring

What you are looking for in the record. When the record does not fit in maxChars, the blocks most relevant to it are shown first and the skipped ranges are marked.

mode'record' | 'thread'

record (default) reads this record. thread reads every record of the Slack thread this message belongs to, oldest first. A Slack record in no single thread reads as itself, then the threads its messages started (at most 10). A record that is not from Slack answers 422.

startRecordinteger

Thread mode: start at this record of the thread, the nextStartRecord of a previous read. Pass the read's nextStartBlock with it.

Response

Successful operation. When the record exists but its content is not indexed yet, content describes the record (name, link, dates) and ends with a Not indexed: paragraph naming its indexing status. When the record is indexed but its stored content could not be loaded, content is the literal No record found. Neither is an error status. An id that does not exist, or a record the caller may not read, answers 403.

contentstring required

The record's full parsed content as a single plain-text string; for a record whose content is not indexed yet, a description of the record and its indexing status instead (see above). In a budgeted read, the part of the record (or thread) that fit. An unbudgeted read returns at most 140,000 characters; a longer record is cut there and the content ends with a truncation marker (see truncated).

truncatedboolean

Present and true only on an unbudgeted read whose content was cut to fit 140,000 characters, marker included. totalChars is then the length of the whole content.

totalCharsinteger

Present only with truncated. The length of the record's whole content, in characters.

mode'record' | 'thread'

Budgeted reads only. Which kind of read this was.

recordIdstring

Budgeted record reads only. The record read.

order'in_order' | 'relevance' | 'extract'

Budgeted record reads only. relevance when query chose which blocks to show; the blocks are then not contiguous. extract when extract=true was asked and the reader model answered: content is the passages it copied out (told to copy word for word; see extract.unverifiedLines), not a page of the record. An extract is one response, so complete is true and nextStartBlock null; whether the reader saw the whole record is extract.sourceComplete.

startBlockinteger

Budgeted reads only. Where this read started (in a thread read, within the record at startRecord).

totalBlocksinteger

Budgeted record reads only. Blocks in the record.

completeboolean

Budgeted reads only. True when nothing of the record (or thread) is left to read after this one. A block larger than the largest maxChars (140000) is returned cut and given up; when nothing follows it, complete is true and truncatedBy is clipped.

truncatedBystring nullable

Budgeted reads. Why the read stopped short: chars, selection, or clipped (a block larger than maxChars was cut; it takes precedence over the others). Null when the read lost nothing. clipped can come with complete: true: a block given up at the largest maxChars with nothing after it.

givenUpBlockinteger nullable

Budgeted record reads only. A block larger than the largest maxChars (140000) that this read cut and gave up: no read can return the rest of it. Set in the read that gave it up, even when more of the record follows.

nextStartBlockinteger nullable

Pass as startBlock to read on; null when nothing is left. In a thread read it is the block of the record at nextStartRecord (0 unless that record was cut short). A block larger than maxChars holds it on that block: send it again with a larger maxChars (up to 140000) to read the block whole.

threadRecordCountinteger

Thread reads only. Records in the thread the caller may see.

startRecordinteger

Thread reads only. Where this read started.

nextStartRecordinteger nullable

Thread reads only. Pass as startRecord, with nextStartBlock as startBlock, to read on. It stays on a record that was cut short until that record has been read to its end. A block larger than maxChars holds the cursor on that block; send the same cursor with a larger maxChars to read it. Null when nothing is left to read, and complete is then true. A block given up at the largest maxChars is named in the text, and its record's entry in records has truncatedBy: clipped.

unreadableRecordIdsstring[]

Thread reads only. Records of the thread the caller may see whose content could not be loaded.

threadsNotReadinteger

Thread reads of a Slack record in no single thread only. Threads of its messages left out because one read covers at most 10.

charsinteger

Budgeted reads only. Characters in content.

maxCharsinteger

Budgeted reads only. The budget this read used.

Changes

  • dbb5e203b445Revision changes
    • warning

      added the new extract enum value to the response property for the response status

    • info

      added the new optional query request parameter extract

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

  • fc76aa045994Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status